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Preface 


This publication is a reference manual that provides Related Publications 

specific information about the use of the IBM 5110 

Computer and the APL language. It also provides « IBM 5110 APL Reference Card, GX21-9304 
information about forms insertion and ribbon 

replacement for the 5103 Printer. This publication is « APL Language, GC26-3847 


intended for users of the 5110 and the APL language. 
» IBM 5110 APL User's Guide, SA21-9302 


Prerequisite Publication « IBM 5110 Customer Support Functions Reference 
Manual, SA21-9311 
IBM 5110 APL Introduction, SA21-9301 


First Edition (December 1977) 


Changes are continually made to the specifications herein; any such changes will 
be reported in subsequent revisions or technical newsletters. 


Requests for copies of IBM publications should be made to your IBM 
representative or the IBM branch office serving your locality. 


A Reader's Comment Form is at the back of this publication. If the form has 
been removed, address your comments to IBM Corporation, Publications, 
Department 245, Rochester, Minnesota 55901. Comments become the property 
of IBM. 


© Copyright International Business Machines Corporation 1977 
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Chapter 1. Operation 


IBM 5110 COMPUTER OVERVIEW 


The IBM 5110 Model 1 (Figure 1) is a computer. The IBM 5110 Model 2 
differs from the Model 1 only in that the Model 2 does not have a built-in tape 
unit. The 5110 has a display screen, keyboard, switches, indicator lights, and 
an adapter for black and white TV monitors. The display screen and indicator 
lights communicate information to the user. The keyboard and switches allow 
the user to control the operations the system will perform. 


Features available for the 5110 are an auxiliary tape unit (Model 1 only), 


printer, up to four diskette drives, a communication adapter, and a serial |/O 
adapter. 
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Keyboard 


Figure 1. IBM 5110 Computer 


DISPLAY SCREEN 


The display screen (Figure 2) can display 16 lines of information at a time, with 
up to 64 characters in each line. Input (information supplied by the user) as 
well as output (processed information) is displayed. The bottom two lines 
(lines 1 and O) of the display contain information entered from the keyboard. 
The cursor (flashing horizontal line) indicates where the next input from the 
keyboard will be displayed. If the cursor is moved to a position that already 
contains a character, the flashing line is replaced by the flashing character. As 
the 5110 processes input, all lines of the display are moved up so that 
information can be entered on the two bottom lines again. The top lines of the 
display are lost as the lines are moved off the display screen. 


Operation 1 


SWITCHES 


The switches on the 5110 (Figure 1) are used for turning power on, restarting 
the system, and controlling how information is displayed. 


Power On or Restart Procedures 


The following switches are used for turning power on to the system or 
restarting the system operation. 


Line Numbers 


3+2 «— Input from the keyboard 
5 «—__—_ Output 


-- «— Cursor (flashing horizontal line) 


-—- = = eo 
OrpP- NWA UIADMN WOODY NW PU 


<«_________——— 64 character positions —————_____-______» 


Normally, to distinguish input from output, input from the keyboard is indented 
and output is displayed starting at the left edge of the display screen. 


Figure 2. The 5110 Display Screen 


BASIC /APL 


Only dual-language machines have this switch. The switch setting determines 
which language will be in operation when power is turned on or after 

RESTART is pressed. If the switch setting is changed after the power is turned on or 
after RESTART is pressed, the language in operation will not be changed. 


Power ON/OFF 


When this switch is in the ON position, power is supplied to the system. The 
system performs internal checks and becomes ready in 15 to 20 seconds. 
When the switch is put in the OFF position, no power is supplied to the 
system. 


Note: The message CLEAR WS is displayed when the system becomes ready. 
If this message is not displayed after 20 seconds, restart the system operation, 
(the RESTART switch is discussed next). 


RESTART 
This switch restarts the system operation. When it is pressed, the system 
performs internal checks and becomes ready in 15 to 20 seconds. The 
message CLEAR WS is displayed when the system is ready. If the system 
does not display the message after 20 seconds, press RESTART again. If the 
system does not become ready after several attempts, call your service 
representative. 
The primary uses of this switch are to restart the system operation after a 
system malfunction has occurred and to change the language in operation on 
dual-language machines. 
Note: Any information you had stored in the active workspace will be lost 
when RESTART is pressed. 

Display Screen Control 
The following switches are used to control how the information on the display 
screen is displayed. 

L32 64 R32 


The three-position switch (positions 64, L32, and R32) operates as follows: 


« 64-Characters are displayed in adjacent positions, and up to 64 characters 
can be shown on each line. 


¢ L32-Characters are displayed in alternate positions (blanks between); only 
the left 32 characters of the 64-character lines are shown. 


« R32~Characters are displayed in alternate positions (blanks between); only 
the right 32 characters of the 64-character lines are shown. 


Operation 


COPY 


Alphameric Keys Numeric keys 
Figure 3. The 5110 Keyboard 


REVERSE DISPLAY 


This switch determines whether the display screen will display light characters 
on a dark background or dark characters on a light background. The brightness 
control may have to be adjusted when the switch setting is changed. 


DISPLAY REGISTERS 
This switch is for the service representative's use when servicing your 5110. 


Note: When you use your 5110, this switch must be in the NORMAL position. 


KEYBOARD 


The 5110 keyboard (Figure 3) has alphameric and numeric keys. The 
alphameric keys are grouped together and are similar to those on a typewriter 
keyboard. When the keys are pressed, the characters entered appear in the 
input line (one of the bottom two lines) on the display screen. The top row of 
alphameric keys can be used to enter numbers; however, numbers can be 
conveniently entered via the numeric keys on the right side of the keyboard. 


The arithmetic symbols (+ - + x) located on the top row of the alphameric 
keyboard can also be entered via keys to the right of the numeric keys. 


When the system power is first turned on, the system is in standard APL 
character mode. In standard APL character mode, you can enter uppercase 
alphabetic characters (without using the shift key), the APL symbols (using the 
shift key), and the APL system command keyword (above the top row of 
numeric keys) and special character combinations (engraved on the front of the 
keys) using the CMD key. 


Note: For combined APL/BASIC systems, there is also a BASIC statement 
keyword engraved on the alphabetic keys. These BASIC statement keywords 
are above the special APL character combinations on the keys. 


You can also place the system in lowercase alphabetic character mode by: 


1. Pressing the HOLD key 


2. Holding down the shift ( ) key and pressing the scroll down 


In lowercase alphabetic character mode, you can enter lowercase alphabetic 
characters (without using the shift key), uppercase alphabetic characters (using 
the the shift key), and the APL symbols using the CMD key. The lowercase 
alphabetic character mode applies only to the alphabetic keys. In lowercase 
alphabetic character mode, you cannot enter the special character combinations 
using the CMD key, because the CMD key is used to enter the APL symbols. 


To return from lowercase alphabetic character mode to standard APL character 
mode: 


1. Press the HOLD key 


2. Hold down the shift key while you press the scroll up ( ) key 


The characters #4 et SEL! and =f "RX are not 
shown on the keyboard; however, you can enter the first group of these 
characters by using the CMD key and pressing the appropriate key as follows: 


Operation 


5 


You can enter the second group of characters using the SHIFT key and 
pressing the appropriate key as follows: 


Note: Some of these characters change when a unique national character set, 
other than EBCDIC, is specified. See Appendix C for more information on the 
unique national graphics. 


The keyboard contains some keys that perform operations other than those 
performed by a typewriter. These keys are discussed in the following text. 
Uses of the APL language symbols on the keyboard are discussed in Chapter 4 
of this manual. 


Attention 


Pressing ATTN (attention) when entering information from the keyboard erases 
everything from the cursor to the end of line O. 


Pressing ATTN when entering information using shared variables to the display 
screen erases everything from the cursor position to the end of the specified 
input area. 


When ATTN is pressed (weak interrupt) during execution of any expression or 
user-defined function, the system stops operation at the end of the statement 
currently being processed. To restart the execution of a user-defined function, 
enter >O1LC. 


Output that was being generated before the system operation stopped may not 
be displayed because there is a delay between the execution of the statement 
that causes the output and the actual display of the output. 


When the shift key is held and ATTN is pressed (strong interrupt) during the 
execution of a statement (either inside or outside a user-defined function), the 
execution of that statement stops as soon as possible. Also, the message 
INTERRUPT, the statement, and a caret (A) that indicates where the statement 
was interrupted are displayed. In this case, the intermediate results might be 
lost, and restarting the function using >UJLC might give incorrect results. 


“@ 
HOLD 


When pressed once, HOLD causes all processing to stop; when pressed again, 

it allows processing to resume. The primary purpose of HOLD is to permit 
reading rapidly changing display information during an output operation or to 
change from one character mode (standard APL or lowercase alphabetic) to the 
other character mode. When the HOLD is in effect (HOLD pressed once), the 
COPY DISPLAY, shift/scroll up, and shift/scroll down keys are active, and the 
characters HOLD are displayed in the lower left corner of the display screen. 


Notes: 

1. Holding down the CMD key and pressing HOLD is restricted to use by the 
service personnel. 

2. When the hold is in effect (HOLD pressed once), holding down the CMD 
key and using the arithmetic keys (+ - + X) on the right side of the 
keyboard are restricted to use by service personnel. 


Execute 


When this key is pressed, the input line(s) of information on the display screen 
is processed by the system. This key must be pressed for any input to be 
processed. 


Command 


In standard APL character mode, when this key is pressed and held, pressing 
an alphameric key in the top row causes the APL command keyword or 
character above that key to be entered in the input line. Also, pressing the 
other key causes the special character combination engraved on the front of 
the key to be entered in the input line. 


In lowercase alphabetic character mode, when this key is pressed and held, 
pressing an alphabetic key causes the APL symbol on the key to be entered in 
the input line. 


Note: Holding down the CMD key and pressing HOLD is restricted to use by 
the service personnel. 


Operation 


Positioning the Cursor and Information on the Display Screen 


The following keys are used to position the cursor and information on the | 
display screen. 


Forward Space S 
> 


When this key is pressed once, the cursor moves one position to the right. 
When this key is held down, the cursor continues to move to the right. When 
the cursor reaches the last position on one input line (line 1 or O), it wraps 
around to the first position on the other input line. 


Insert 


When the CMD key is held down and the forward space key is pressed once, 

the characters at and to the right of the cursor position (flashing character) are 
moved to the right one position, and a blank character is inserted at the cursor 
position. The cursor does not move. For example: 


Flashing Character 
Before the insert operation: 123567 
After the insert operation: 123 7567 


When these keys are both held down, the characters continue to move to the 
right and blank characters continue to be inserted. 


Note: If there is a character in position 64 of line 0, the insert operation will 
not work. 


Backspace S 
PS 


When this key is pressed once, the cursor moves one position to the left. 
When it is held down, the cursor continues to move to the left. When the 
cursor reaches position 1 on one input line (line 1 or O), it wraps around to the 
last position on the other input line. 


Delete 


When the CMD key is held down and the backspace key is pressed once, the 
character at the cursor position (flashing character) is deleted and all characters 
to the right are moved over one position to the left to close up the space. The 
cursor is not moved. For example: 


Before the delete operation: 1234456 
Flashing Character 
After the delete operation: 123456 


When these keys are both held down, the characters at the cursor position 
continue to be deleted and all the characters to the right are moved to the left. 


Scroll Up 


When this key (located above the numeric keys) is pressed once, each 
displayed line is moved up to the next line. As the lines are moved up, the top 
line is lost as it is moved off the display screen. When this key is held down, 
the lines continue to move up. 


When you are doing input/output operations to the display screen using an 
APL shared variable, the cursor is moved up one line when this key is pressed. 
When this key is held down, the cursor continues to move up until the top line 
is reached. 


When the system is in the hold state (the HOLD key has been pressed once), 
holding down the shift key and pressing this key causes the system to be in 
standard APL character mode. 


Scroll Down 


When this key (located above the numeric keys) is pressed once, each 
displayed line is moved to the next lower line. As the lines are moved down, 
the bottom line is lost as it is moved off the display screen. When this key is 
held down, the lines continue to move down. 


When you are doing input/output operations to the display screen using an 
APL shared variable, the cursor is moved down one line when this key is 
pressed. When this key is held down, the cursor continues to move down 
until the bottom line is reached. 


When the system is in a hold state (the HOLD key has been pressed once), 


holding down the shift and pressing this key causes the system to be in 
lowercase alphabetic character mode. 


Operation 


Copy Display 
x 


If there is a 5103 Printer, when the CMD key is held down and this key is 
pressed once, all the information presently on the display screen is printed. 
COPY DISPLAY is operational even when the system is in the hold state (the 
HOLD key has been pressed once). . 


Note: The L32 64 R32 switch has no effect on what will be printed. 


INDICATOR LIGHTS 


The 5110 (Figure 1) has two indicator lights. 


Process Check 


When on, the PROCESS CHECK light indicates that a system malfunction has 
occurred. In this case, press the RESTART switch to restart the system 
operation. If the system operation cannot be successfully restarted after 
several attempts, call your service representative. After the system operation is 
restarted, you must reload any user-defined functions or data that was 
previously in the active workspace. 


In Process 
The IN PROCESS light is on when the system is processing data and the display screen is 
turned off during the execution of a user-defined function (see the ICC 
system function in Chapter 5). The light goes off when: 


« The display screen is turned on using the JCC system function 


« A statement in the user-defined function generates results that are to be 
displayed 


« Execution is completed and the cursor returns 
Note: If the display screen is blank (no data or cursor is displayed) and the IN 


PROCESS light is off, check the brightness control before calling your service 
representative. 
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DATA REPRESENTATION 


Numbers 


The decimal digits 0 through 9 and the decimal point are used in the usual 
way. The character , called the negative sign, is used to denote negative 
numbers. It appears as the leftmost character in the representation of any 


number whose value is less than zero: 


Q-- 


The negative sign, _, is distinct from - (the symbol used to denote 
subtraction) and can be used only as part of the numeric constant. 


Scaled Representation (Scientific Notation) 


You can represent numbers by stating a value in some convenient range, then 
multiplying it by the appropriate power of 10. This type of notation is called 
scaled representation in APL. The form of a scaled number is a number 
(multiplier) followed by E and then an integer (the scale) representing the 
appropriate power of 10. For example: 


Number Scaled Form 
f_ Multiplier 
66700 6.67E4 
Scale 
.00284. 2.84E 3 


The E (E can be read times ten to the) in the middle indicates that this is scaled 
form; the digits to the right of the E indicate the number of places that the 
decimal point must be shifted. There can be no spaces between the E and the 
numbers on either side of it. 


Numeric Value Range 
Numeric values in the 5110 can range from _7.237005577332262E75 to 


7.237005577332262E75. The smallest numeric value the 5110 can use is 
+5.397604346934028E 79. 
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Numeric Value Precision 


Numbers in the 5110 are carried internally with a precision of 16 significant 
digits. 


Note: As with all computers, some values cannot be expressed exactly, and 
certain computations are not fully accurate in the least significant (16th) digit. 


Character Constants 


Zero or more characters enclosed in single quotes, including overstruck 
characters (see Appendix B) and blank characters (spaces), is a character 
constant. The quotes indicate that the characters keyed do not represent 
numbers, variable names, or functions, but represent only themselves. When 
character constants are displayed, the enclosing quotes are not shown: 


“ARCTIEF G ' If the closing quote is not 


ARCTIERG entered, the 5110 
"YS SARC! automatically supplies the 
L23AaRnC closing quote when EXECUTE 
Me THE ANSWER TS: * is pressed. 
M 


THE ANSWER TS: 


When a quote is required within the character constant, a pair of quotes must 
be entered to produce the single quote in the character constant. For example: 


“TON ' CT GIVE THE ANSWER AWAY’ 
NON YT GIVE THE ANSWER AWAY 


Logical Data 


Logical (Boolean) data consists of only ones and zeros. The relational functions 
(> > = < < #) generate logical data as their result; the result is 1 if the 
condition was true and 0 if the condition was false. The output can then be 
used as arguments to the logical functions (A~ VV~) to check for certain 
conditions being true or false. Logical data can also be used with the 
arithmetic functions, in which case it is treated as numeric 1’s and O's. 


STORAGE REQUIREMENTS 


The following list shows how many bytes of storage are required for each data 


type: 
Data Type Number of Bytes Required 
Character constant 1 byte per character 
Whole numbers that are equal to 4 bytes 


or less than 231-1 


Whole numbers that are greater 8 bytes 

than 23'-1 

Decimal numbers 8 bytes 

Logical data 1/8 Byte (1 byte can contain 8 


ones or zeros) 
Variable Name Number of Bytes Required 


-3 characters or less 12 bytes+(4x rank 
(0 Pp VARIABLE)) bytes 


4 characters or more 1 byte per character+21 
bytes+(4xrank (9 9 VARIABLE)) 
bytes 


Note: All storage is allocated in 4 byte increments. 


5110 STORAGE CAPACITY AND MODELS 
The 5110 Models 1 and 2 can have a storage capacity of 16K (K = 1024 


bytes), 32K, 48K, or 64K. The first digit in the model number indicates the 
model, and the second digit indicates the storage capacity as follows: 


Storage Model Number | Model Number 
Capacity with Tape without Tape 


16K Ail A21 
32K A12 A22 
48K A13 A23 
64K A114 A24 
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Figure 4 shows how the storage is allocated for the various requirements on a 
base 5110 (Model A11 or A21). 


Active Workspace 


10,600 
Bytes 


Symbol Table (see note) 


5784 5110 Internal Storage Requirements for Pointers, 
Bytes Counters, etc 


Note: The symbol table requires 8 bytes of storage for 
each symbol allowed in the active workspace (see SYMBOLS 
in Chapter 3). 


Figure 4. Storage Allocation for a Model A11 5110 


Notice that the workspace available to the user (active workspace) is 10,600 
bytes, while the rernaining bytes are used for internal purposes. In the other 
models, all additional storage is allocated to the active workspace. For 
example, on the Model A14, the active workspace is approximately 60,000 
bytes. 


PERFORMANCE CONSIDERATIONS 


Turning the Display Screen Off 


The internal processing capability of the 5110 is increased by approximately 
18% when the display screen is turned off during the execution of a 
user-defined function. The ICC (console control) system function is used to 
turn the display screen on and off. For example: 


x<«1Q0CCO This statement turns the display screen off. 
X«10CC 1 This statement turns the display screen on again. 


(See The LICC Function: Console Control in Chapter 5 for a complete 
description of the LICC function.) 


Overlapped Printing | 


When data is sent to the printer, the 5110 continues (overlaps) internal 
processing as the last print line is being printed. For example: 


When FUNCTION is executed, the 


VFUNCT ION 


Pi 10 a0et.i00) 5110 starts processing statement 2 as 
Red € yO. #e¥ the last line of the matrix generated in 


statement 1 is printed. 
Therefore, to get maximum performance when data is sent to the printer, send 
the data to the printer in smaller segments. The following examples show how 
the data might be sent to the printer in smaller segments: 


Example 1 


YO PRINTI; A; B30; 0 


In this example, all the data is sent to the printer by statement 5. The 
overlapped printing capability is not used. 


Example 2 
Y PRINTS; B;0;0 
oo ' COLUMN COLUMN? COLUMNS COLUMNG COLUMNS * 
ean (le 8 O Be TO S etihd) 
ma tle & O ee4e/ 010 B) 
po] sti 
Lav Y 
In this example, statement 2 is processed as the data from statement 1 is 
printed. 
Example 3 


Y PRINTS; B;C 
es ‘COLUMN TD COLUMN? COLUMNS COLUMN COLUMNS ° 


Lael 8S 0 yRe 10 35 ptaisd? 
pad 2 0 rt/0 11 &B 
oe V 


In this example, statement 2 is processed as the data from statement 1 is 
printed, and statement 3 is processed as the last line of data from statement 2 
is printed. 
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VARIABLE AND FILE NAMES 


A variable name can be up to 77 characters in length with no blanks; the first 
character must be uppercase alphabetic or underscored uppercase alphabetic, 
and the remaining characters can be any combination of uppercase alphabetic, 
underscored uppercase alphabetic, and numeric characters. Variable names 
longer than 77 characters can be used, but only the first 77 characters are 
significant to the 5110. 


Note: Do not use SA or TA as the first 2 characters in the variable name (see 
Trace and Stop Controls in Chapter 6). 


The data file names that are allowed by the 5110 depends upon the type of 
file and storage media used: 


« Workspace file on tape. The file name can be any combination of up to 11 
alphabetic and numeric characters (with no blanks); the first character must 
be alphabetic. For example: 


FILE2 
If more than 11 characters are entered, only the first 11 are used. 


¢ Data file on tape. The file name can be any combination of up to 17 
characters (including blanks). For example: 


2 DATAFILE 


If more that 17 characters (including blanks) are entered, an INVALID 
PARAMETER error message is displayed. 


« Workspace file on diskette. The file name can be any simple name. A simple 
name is any combination of up to 8 alphabetic and numeric characters (with 
no blanks); the first character must be alphabetic. For example: 


FILEONE 


If more than 8 characters are entered as the file name, an INVALID DISK 
FILE NAME message is displayed. 


» Data file on diskette. The file name can be a simple or complex name. A 
complex name is two or more simple names, with each name separated by 
a period(.). A complex name cannot exceed 17 characters including the 
period. For example: 


DATA.FILE 

A period must separate two simple names. 
FILENAME For one simple name, a period is not required. 
FILE.NAME Complex names. 
DISKETTE.FILENAME 


Note: The names SYSAREA and ERRORSET are used by the system. You 
should not use these names as diskette file names. 
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NAME PROCESSING 


Following is a description of how the system uses the device/file number and 
file ID parameters specified for system commands (see Chapter 3) or 
input/output operations (see Chapter 7). 


For operations to tape files: 
* The device/file. number parameter must always be specified. 


e The file ID parameter is optional, except for the )DROP command. When 
this parameter is specified, the specified file ID is checked against the tape 
file ID, and the operation fails if the file IDs do not match. 


For operations to diskette files: 


e If only the device/file number parameter is specified, the operation is 
performed to the specified diskette file. 


e If only the file 1D parameter is specified, the diskette files on each diskette 
drive are checked for the specified file ID. The specified file 1D must be 
unique on the diskette(s), and the operation is performed to the appropriate 
diskette file when a match is found. 


e If both the device/file number and file ID parameter are specified, the 
specified file ID is checked against the specified diskette file ID, and the 
operation fails if the file [Ds do not match. 


Note: If the specified file number is 000 (for example, 11000 is diskette 
drive 1, file number OOO), the diskette files on the specified diskette drive 
are checked for the specified file ID, which must be unique on the diskette. 
The operation is performed to the appropriate diskette file when a match is 
found. 


PROCEDURE FILE 


A procedure file provides an alternative to entering input from the keyboard. A 
procedure file can contain any executable expression or statement that can be 
entered from the keyboard: for example, system commands, function 
definition, and APL expressions. When the. )PROC command is issued (see 
Chapter 3), these expressions or statements from the procedure file replace the 
input from the keyboard. 


Creating a Procedure File 


A procedure file can be a sequential access type | (file type 2) or direct access — 
type | or U (file type 9) data file. Each record in the procedure file represents 
one statement or expression to be executed by the 5110. These records cannot 
be greater than 128 characters. See Chapter 7 for more information on 

creating data files. 
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Using a Procedure File 


The )PROC command is used to initiate input from the procedure file. Once 
the )PROC command is issued, the records (expressions or statements) in the 
specified procedure file are sequentially read, displayed, and executed. The 
results of the executed statements or expressions are also displayed. When 
records are executed from a procedure file, except for direct access input from 
the display screen (see Entering Data from the Keyboard later in this chapter), 
all keyboard equivalent input comes from the procedure file. This includes the 
response for LJ input [| input, and the ALREADY MARKED message. For 
example: 


OUiti~<—This user-defined function is executed from a procedure 
i: file. 


3 The function requests 0 input. 


The response for the 0) input must be the next record in 
the procedure file. 


If an error occurs on a statement or expression executed from the procedure 
file, an error message is displayed, and the next record on the procedure file is 
read and executed. The 5110 continues to read and execute input from the 
procedure file until one of the following occurs: 


e The last record is read from the procedure file. 


« A strong interrupt is entered (hold down the shift key and press the ATTN 
key). 


¢« Another )PROC command is issued. In this case, the input then comes from 
the new procedure file, and control is not returned to the previous procedure 
file. 

« An 1/O error occurs when the 5110 is reading the procedure file. 


* The )LINK command is issued from the procedure file. 


Except when another )PROC command is issued, the 5110 returns to using 
keyboard input when one of the previous conditions occurs. 


Doing Input/Output Operations 


When using a procedure file, you can use shared variable to do input/output 
operations such as: 


Read records from and write records to a data file. 


Note: If the procedure file is a sequential access tape data file, the tape is 
repositioned if input/output operations are performed on the same tape that 
the procedure file is on. This causes an error when the next physical read 
of data from the procedure file occurs. However, since each physical read 
from the tape procedure file consists of 512 characters, a tape procedure 
file with less than 512 characters can also be used to perform input/output 
operations. In this case, the last command in the 512 characters should be 
)PROC to return the 5110 to keyboard entry. 


Read records from and write records to the display screen. This allows you 
to enter data from the keyboard when using a procedure file. 


Read records from and write records to the procedure file. This allows you 
to update the procedure file as the records are read from the procedure file 


and executed. 


Send data to the printer. 


See Chapter 7 for more information on these input/output operations. Entering 
data from the keyboard and updating the procedure file is discussed next. 
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Entering Data from the Keyboard 


Even though the records from the procedure file replace keyboard input, you 
can enter data from the keyboard using a pair of shared variables and direct 
access to the display screen. For example, assume you are using a procedure 
file and the following user-defined function has already been copied into the 
active workspace: 


VEX@AMPLEENTE REET 
Y EXAMPLEENTER J CTL: DAT IA 
fp De SE ME PDE HE DE DE NG YE FE HE ME OE DE DE DE DE ME DE DE IG 9G IG IE IE DE ME DG IE OE DE IE He De YE OE DE 2 DG De DE OE 6 DE HE OE DE DE DE OE a OE ME 
AQFEER VARTARLE NAMES TO RE SHARED 
Ae) TSVO 2 8 ep CTLGAT: 
Ov COR ADD AE RROR GD 
fy He ME DE IE DE DE DE DE IE DE HE IE DE IE Ie IG IE I IE ME DE HE 9G ME DE IG DE HE IG DE SE MG DG IE IE OE SE AE ME DE DE DE IE NE EOE OE DG DE DE 9G EE 
ASPECIEY INPUT/OUTPUT GPERATIONS TO THE OTSPLAY 
The TUES PLAY * 
tO. ECTLO ZERRORS 
“ENTER NEW Dat nas When this statement is executed, the cursor appears at character position 
OTLé 8 FOR 220 903 on the display screen. Now, you can enter 120 characters from the 
tC OC. EOTLOZERROR? keyboard. 
fy JE HE HE DE IE HE DE IE IE DE YE IG HE DE DE Me IE IE IE DE DE DE 2G IE IE IE IE NE NE 9G 9G IE DE DE De dE 9G OE OE GG 9G 96 OE IE DE de 96 26 OE ae OE ae Me 
AGL SPLAY THE INFORMATION FROM Yi KEYBOARD 
tia 1 ——_—_—_———— After the data is entered from the keyboard and EXECUTE is pressed, the 
+O 120 characters starting from position 903 are assigned to DAT. 
Gy HE DE DE Me De Me DM I De DY DE SE Ne ME DE DE IE ME DE SE IE DE PE SE IE NE FE IE DE IE OE GG SEE DE OE 2G DE 9G OE 2G 6 20 Oe OE YE HEE OE 2b DE 
BERROR MESSAGES 
ERRORDTS THE SHARED VARTARLE OFFER FATED 
ERRORZ: ENTERING ATA FROM THE KEYBOARD FATLETN 


Now when the record EXAMPLEENTER is read from the procedure file and 
executed, you will be able to enter data from the keyboard. 


Updating a Procedure File on Diskette 


When using a procedure file that is on a diskette, you can also do direct 
access input/output operations to the procedure file. This allows you to 
update records (statements or expressions) before they are read and executed. 


If a procedure file is to be updated, it is recommended that the procedure file 
be a type U data file, because a type U data file has only one record per 
sector and the 5110 reads one sector at a time when executing records from a 
procedure file. Type | data files might have more than one record per sector, 
and the records can cross sector boundaries. Therefore, when a sector is read, 
the data read might include more than one record. For example: 


Sector Boundaries 


Tox Tooey [amor [| 
\cemeanstne enemas tetrsemmmnermnseaeemecanee/ 


When this sector is read, both record X and record Y are read into the system. 


Type | Data File 


In the previous example, if record X executes a user-defined function that 
updates record Y (see the following example), record Y has already been read 
into the system and the updated record is not executed from the procedure 
file. Instead, the original record Y is executed. 
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Following is an example of a user-defined function that allows you to enter 
information from the keyboard and to update the procedure file with the 
information you entered. 


In this example, assume that you are using a procedure file, and that the 
user-defined function has already been copied into the active workspace. 


VEXAMPLEWRTTERCY 
VY EXA@AMPLEWRITE  / CTLXSCTLYS ATK TATY: A: & 
1 IE IG IE IE IG NE DE IE IE ME IE DE IG 9 DE DE IE IE DE Me ME HE ME DE Te ME He Me He ME DE DE DE DE HE 9G IE 9G IE IE IG IE IE IE 96 96 9G IE OG OG Oi OE OE OE OE 
} AQFRIER THE VARTARLE NAMES TO BE SHARED 
| Ae) TSVO YM e CTLXGATEKETLYUATY ' 
| tive COCA CER ROR I 
SY Ry ME NE IG IG IE HE 9G IE 9G IE UE IE IE IE FE FE DE IE IE IE IE DE SE SE DE OE IE ME IE I FE I IE NE ME NE Ne DE DE DE IE 9G FE 9G IE FE IE IE IG IE FE OE 98 OE IE 96 
1 wSPECIFY THE TN PUT/OUTPUT GQPERATIONS TO THE THSPLAY AND 
|! aATHE PROCEGURE FLA 
| CTL  TISPLAY' 
| COC. POCTL EO ZERRORS 
POOTRYe TOR 11001 "——— In this example, the procedure file is on diskette drive 1, file 1. 
FC OST FOTO CER ROR 
] 6) 9G IE DE IE 9G IE IE IG I IG Me De ME ME ME DH ME Die De IE ME DE IE I NE SE IE ME DE Me ME Ne DE DE DE DE DE IG DG IE IE 9G OE IG IE IE OE IE IE IE IE OE 26 96 IE OE 
, A®ENTER TATA FROM THE KEYEOART 
| "ENTER THE RECORD NUMBER TO GE UPDATE 
1 OTe @ Fas & 
1 4 COLT OTIEO CE RROR? 
} eat xX -————-—_————~ The new record number is assigned to B for later use in this 
| "ENTER THE NEW RECCRG:' user-defined function. 
f CTLXe® 8 896 T27 
1 68 COS. FETLXO CE RRORD DATY must contain the information to be written to the procedure file. 
Lb OTL KE 0 Note, in this example, that the procedure file contains 128-byte 
wb TAT Ye@ 2a ea TX character records. 
1 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 
| 


fe DG 9G He DE IG IG IG DE IE IE IE DE IG IG IE 9G DE IE DE IE DE DE IE IE DE DE 9G IG NE DE ME IG DE HE 9G IE IE ME AG OE IE FE DE DE IE IE IE HE OG IE IG DE OE EE 
AUPODATE THE PROCETURE FTE 

Oe Yee A ABD yh 

SCOT POTLY) “ERRORS 


ay CTL Yea 0 

ee “PROCETHURE FTI UP ta TET 

ey + 

TAC TD 96 26 96 96 96 D6 96 26 OE IE OE 6 HE DE IE DE HE DE DE DE IE 96 DE DE IE FE JE IE DG IE YE IE DE IE DE OE DE OE DE OE DE aE IE IE IE IE IE DE IE DE IE TE OE HE IE Me 
S120 aE RROR MESSAGES 

S20 ERRORD: THE SHARED VARTARBLE OFFER FATE 

Oa +f) 

SHO ERRORS CENTERTAG GATA FROM THE KEYEROARD FATLEn 


oo} {i 
ERROR CUPOQATING THE PROCE TURE FYE FeATLEn 
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TAPE DATA CARTRIDGE HANDLING AND CARE 
¢ Protect the tape data cartridge from dust and dirt. Cartridges that are not 
needed for immediate use should be stored in their protective plastic 
envelopes. 
¢ Keep data cartridges away from magnetic fields and from ferromagnetic 
materials that might be magnetized. Information on any cartridge exposed 


to a magnetic field could be lost. 


¢ Do not expose data cartridges to excessive heat (more than 130°F [54°C }) 
or sunlight. 


e Do not touch or clean the tape surface. 

¢ If a data cartridge has been exposed to a temperature drop exceeding 30°F 
(-1°C) since the last usage, move the tape to its limits before using the 
tape. The procedure for moving the tape to its limits is: 


1. Use the )LIB command to move the tape to the last marked file. 


2. Use the )MARK command to mark from the last marked file to the end 
of the tape. For example: 


JMARK 20 10 n 
where n is the number of the last marked file, plus one. 
3. - When ERROR 012 (end of tape) is displayed, use the )REWIND 
command to rewind the tape. 
TAPE HEAD CLEANING PROCEDURE 
Occasional cleaning of the tape read/write head provides more reliable 
operation of the tape drive. Use a soft lint-free cloth or paper towel 


dampened with isopropyl alcohol to clean tape oxide from the tape head. Then 
wipe the tape head dry. 


Tape Read/Write Head 


Tape Drive Opening 
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DISKETTE HANDLING AND CARE 


Diskette Insertion 


CAUTION 

If a diskette has been exposed to temperatures outside the range 50°F to 
125°F (10°C to 51°C), keep the diskette at room temperature for about five 
minutes before inserting it in the diskette drive. 


1. Open the diskette drive cover. 


2. Remove the diskette from its envelope by grasping its upper edge and 
and listing. 


3. Insert the diskette into the diskette drive. 


Note: The permanent diskette label must be in the lower right corner as the 
diskette is inserted in the drive. 


4. Close the diskette drive cover only after the diskette is fully inserted. 


Diskette Removal 
1. Open the diskette drive cover (only when the cursor is flashing). 


2. Remove the diskette by grasping its upper edge and pulling it straight 
out. 


3: Return the diskette to its envelope. 


Handling Defective Cylinders 
With use, the diskette can develop areas on which readable records cannot be 
written. A diskette with a defective area should be reinitialized to use one of 
the alternate cylinders available. See the [BM 5110 Customer Support 
Functions Reference Manual, SA21-9311, for information on the initialization 
function. 


Note: Before reinitializing a diskette, copy any useful data from the diskette 
onto another diskette. 


After the diskette has been reinitialized, record the number of the defective 
cylinder on the permanent label. 

Handling Precautions 
Do not bend or fold the diskette. 


Do not use rubber bands or paper clips on the diskette. 
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Do not eat, smoke, or drink while handling the diskette. 


Do not use magnets or magnetic objects near the diskette. Data can be lost 
from a diskette that is exposed to a magnetic field. 


Do not place heavy objects on the diskette. 


Do not erase labels attached to the diskette, or make any erasures on or near 
the diskette. Erasure residue could get in the diskette, and this should be 
avoided. To discourage erasures, it is recommended that you use a fiber-tip or 
ballpoint pen when marking on the diskette labels. Mark temporary labels 
before attaching them to the diskette. Alter the temporary labels with the 
diskette in the envelope. 


DEVICE ADDRESSING 


The device address for the 5110 tape units and diskette drives are as follows: 


Device Device Address 
Built-in tape unit 1 
Auxiliary tape unit 2 
Diskette drive 1 11 
Diskette drive 2 12 
Diskette drive 3 13 
Diskette drive 4 14 
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The following illustration shows the device address for diskette drives attached 
to the 5110: 


Device Address 12 Device Address 14 
Device Address 13 


Device Address 1.1 


UNH ANY in ; 


Th WoT 


ty 


DEFAULT DEVICE 


The default device is the tape unit or diskette drive used by the system when 
only the file number is specified. For example: 


)LOAD 3 DATA 


Fewer than four digits are specified; therefore, the value 
specified represents only the file number, and the 
default device is used. - 


For the Model 1, the default device is the built-in tape unit (1). For the Model 2, the 
default device is the first diskette unit (11). 


CUSTOMER SUPPORT FUNCTIONS 
The following customer support programs are provided with the 5110: 
« Tape-to-tape copy 
« Diskette-to-diskette copy 
e« Diskette-to-tape copy 
¢ Diskette initialization 
e Generalized loader 
e Diskette recovery 
e Tape recovery 
« Diskette Compress 
« Label display 
See the IBM 5110 Customer Support Functions Reference Manual, SA21-9311, 
for a complete description of each program. 
AUDIBLE ALARM 
The 5110 has an audible alarm feature that can be used to signal the operator. 
For example, the audible alarm can signal the completion of a user-defined 
function or a procedure file (see Procedure File in this chapter). The DCC 
system function sounds the audible alarm (see Chapter 5). For example: 
To sound the audible alarm, the left argument must be a 2. 


20CC 222 


L__the audible alarm sounds for approximately 1/4 second for 
each 2 in the right argument. 
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Chapter 3. System Commands 


OVERVIEW 


The 5110 contains an active workspace, which is the part of internal storage 
where the user's data and user-defined functions (programs) are stored. When 
the power is turned off or the RESTART switch is pressed on the 5110, all the 
data in the active workspace is lost. However, the contents of the active 
workspace can be saved on tape or diskette (stored workspace) and then read 
back into the active workspace for use at a later time (see System Command 
Descriptions in this chapter). The contents of the active workspace then exist in 
both the active workspace and on tape or diskette. 


The tape and/or diskette is your library; that is, it is a place where you can 
store data for later use. Before a tape or diskette can be used, it must be 
formatted. A formatted tape or diskette contains one or more files where data 
can be stored. Each file has a file header, which contains information about 
the file. See the )LIB system command in this chapter for a description of the 
file header. 


The system commands, which are used to control and provide information 
about the system, are discussed next. 

SYSTEM COMMAND DESCRIPTIONS 
The following list shows how system commands are used to control and 


provide information about the various parts of the system. Each system 
command is described in detail later in this chapter. 
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Command 
)CLEAR 
)COPY 
)ERASE 
)LOAD 


)PCOPY 


)SYMBOLS 


)WSID 


)RESUME 


Command 


)CONTINUE 


)DROP 
)FILEID 
)MARK 
)FREE 


)SAVE 


)PROTECT 


)VOLID 


Commands That Control the Active Workspace 


Meaning 

Clear the active workspace. 

Copy stored objects (see note 1) into the active workspace. 
Erase global objects (see note 1) from the active workspace. 
Replace the active workspace with a stored workspace. 
Copy stored objects (see note 1) into the active workspace, 
and protect objects in the active workspace from being 


destroyed. 


Change the number of symbols allowed in the active 
workspace. 


Change the active workspace ID. 
Replace the active workspace with a workspace stored using 


the )CONTINUE command, and reestablish the system 
environment as it was when the workspace was stored. 


Commands That Control the Library (Tape and/or Diskette) 


Meaning 

Write the contents of the active workspace on tape or 
diskette. The active workspace can contain suspended 
functions and open shared variables. 

Drop a tape or diskette file. 

Change the file name on a diskette volume. 

Format the tape or diskette. 

Make a diskette file available for reallocation. 

Write the contents of the active workspace on tape or 
diskette. The active workspace cannot contain suspended 
functions or open shared variables. 


Invoke or remove the write-protect feature on a diskette file. 


Change the volume ID or access protection indicator of a 
diskette device. 


Commands That Provide Information about the System 


Command 
)FILEID 
)FNS 

)LIB 

)SI 

)SINL 


)SYMBOL 


)VARS 
)VOLID 


JWSID 


Meaning 

Display the file name on a diskette volume. 
Display the names of the user-defined functions. 
Display file headers. 

Display the state indicator. 

Display the state indicator and local names. 


Display the number of symbols allowed and used in the active 
workspace. 


Display the names of the global variables. 
Display the volume ID of a diskette device. 


Display the active workspace ID. 


Other Commands That Control the System 


Command 


)LINK 


JOUTSEL 
)PROC 
JREWIND 
)SORT 


Notes: 


Meaning 


Load microcoded programs, such as functions or 
asynchronous communications. 


Select printer output. 
Open a procedure file. 
Rewind the tape. 


Transfer system control to the sort function. 


1. Objects refers to both user-defined functions and variables. 

2. The system commands )CONTINUE, )COPY, )DROP, )LOAD, )MARK, 
)REWIND, and )SAVE will blank the top 8 to 12 lines on the display screen 
when they are used. 


All system commands (and only system commands) have as their first 
character a right parenthesis. Each system command must begin on a new 
line. Parameters (required or optional information) for the system commands 
must be separated by blanks. 
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Some system commands can be entered two ways: 


¢ The system command can be entered one character at a time from the 
keyboard. 


e The system commands )LOAD, )SAVE, )CONTINUE, )LIB, )FNS, )VARS, 
)COPY, )WSID, )OUTSEL, and )MARK can be entered in one operation if 
you hold down the CMD key while pressing the top-row key just below the 
label of the command you want. 


System commands can be executed two ways: 
e Press EXECUTE after the parameters, if required, are entered. 


« Read the system command and required parameters from a procedure file 
(see The )PROC Command in this chapter). 


System commands cannot be used within APL expressions and cannot be used 
as part of a user-defined function (see Chapter 6). 


Following is an explanation of some terms and symbols used as parameters for 
system commands: 


¢ Device/file number specifies the device and file to be used. The built-in 
tape unit is device 1, the auxiliary tape unit is device 2, diskette drive 1 is 
device 11, diskette drive 2 is device 12, and so on. If the value specified is 
less than four digits, the default device is assumed and the value specified 
represents only the file number (see Defau/t Device in Chapter 2). !f the 
value specified is greater than three digits, the rightmost three digits specify 
the file number and remaining digits specify the device. For example: 


Device/File Number Meaning 


1 For a 5110 Model 1—Tape unit 1, file 1 

For a 5110 Model 2—Diskette drive 1, file 1 
2002 Tape unit 2, file 2 
12002 Diskette drive 2, file 2 


¢ Workspace ID specifies the name of the stored workspace on the media. 
See Variable and File Names in Chapter 2 for a description of the valid file 
names. 


« Password is any combination of up to 8 alphabetic or numeric characters 
(with no blanks). If more that 8 characters are entered, only the first eight 


are used. 


e Object is a user-defined function or variable name. 


»« Parameters enclosed in brackets can be optional in certain cases. 


Note: See Name Processing in Chapter 2 for information on when the 
device/file number and file ID parameters are optional for tape and diskette 
operations. 


The )CLEAR Command 


The )CLEAR command clears the active workspace. A cleared workspace has 
no valid name and contains no user-defined variables or functions and no data. 
The workspace attributes are set to: 


Index origin -- 1 
Workspace identification — CLEAR WS 
Comparison tolerance - 1E 13 
Printing width - 64 

Printing precision - §5 

Random number seed — 16807 
Data printed - ALL 
Symbols - 125 


When the command is successfully completed, CLEAR WS is displayed. 


Syntax 
)CLEAR 


There are no parameters. 


The )CONTINUE Command 


‘The )CONTINUE command, using the specified workspace ID, stores the 
contents of the active workspace onto tape or diskette (the media) without 
changing the active workspace. Primarily, this command stores active status, 
such as suspended functions, so that an operation can be resumed later on the 
same or a similar machine. When the command is successfully completed, 
CONTINUED device/file number workspace ID is displayed. 
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The )CONTINUE command on the 5110 is similar in function and format to the 
)SAVE command (except as noted below). 


Notes: 


1, 
2. 


10. 


11. 


Syntax 


A clear workspace cannot be written on the media. 

A workspace with suspended functions can only be written on the media 
with the )CONTINUE command (it cannot be written to the media by the 
)SAVE command). 

)COPY and )PCOPY commands cannot specify stored workspaces that 
were written on the media by the )JCONTINUE command. 

A stored workspace written to the media by the JCONTINUE command 
cannot be loaded into a 5110 active workspace that is smaller than the 
original active workspace. 

If a stored workspace that was written to the media by the JCONTINUE 
command is loaded into another 5110 with a larger active workspace, the 
workspace available (see the LWA system variable in Chapter 5) is the 
same as when the workspace was written to the media. 

lf ATTN is pressed during a )JCONTINUE operation, the system operation 
is interrupted and the file is set to unused. 

Shared variable execution status can be stored by the )JCONTINUE 
command. A subsequent )RESUME allows the user to resume execution 
if the media is restored to the same condition as when the workspace 
was stored by the )CONTINUE command (see The )RESUME Command in 
this chapter). 

The LILX system function is executed if the stored workspace is loaded 
by the LOAD command. However, the LILX system function is not 
executed if the workspace is loaded by the JRESUME command. 
Workspaces are stored and loaded into the active workspace faster by 
the )CONTINUE command than by the SAVE command. 

IMFs (internal machine fixes) are not stored by )JCONTINUE. If an IMF 

is required for operation of the stored workspace, it should be reapplied 

by the )LINK command (if the IMF is not already in the system) before the 
workspace is reloaded. 

Workspaces stored on tape by the )CONTINUE command cannot be 
interchanged between the IBM 5110 and the IBM 5100. 


)CONTINUE [device/file number] [workspace ID] [:password ] 


Where: 


device/file number (optional) is the number of the device and file on the 
device where the contents of the active workspace are to be written. If no 
device/file number is specified, the device/file number from which the 
active workspace was loaded or specified by a previous )WSID command is 
used. 


workspace ID (optional) is the name of the workspace to be stored. This 
name must match the workspace ID of both the active workspace and the 
file to be used on the media unless the file is marked unused. If the file is 
marked unused, the active workspace ID and file workspace ID are changed 
to this workspace ID. If no name is specified in the command, the name of 
the active workspace is used. 


:password (optional) is any combination of up to 8 alphabetic or numeric 
characters (without blanks), preceded by a colon. This sequence of 
characters must be matched when the stored workspace is to be read back 
into the active workspace. If no workspace ID or password is entered, the 
password associated with the active workspace (if any) is assigned to the 
workspace being stored. If just the workspace ID and no password is 
entered, any password associated with the active workspace is not used. 


The )COPY Command 


The )COPY command copies all or specified global objects from a stored 
workspace to the active workspace. Only objects in stored workspaces that 
were written on the media with the )SAVE command can be copied. When the 
command is successfully completed, COPIED device/file number workspace ID 
is displayed. 


Notes: 

1. If the active workspace contains suspended functions, objects cannot be 
copied into it. 

2. If the ATTN key is pressed during a )COPY operation, the system operation 
is interrupted and the amount of information copied into the active 
workspace is unpredictable. 

3. If the active workspace contains shared variables, objects having the same 
name as a shared variable cannot be copied into the active workspace. 


Syntax 
JCOPY [device/file number] [workspace ID] :password [object name(s) ] 


Where: 


device/file number (optional for diskette only) is the number of the device, 
and workspace file the objects are copied from. 


workspace ID (optional) is the name of the stored workspace on the media. 
This parameter is optional only if the device/file number is specified. 


:password is the security password assigned by a previous )WSID or )SAVE 
command. If no password was assigned previously, a password cannot be 
specified by this command. 


object name(s) (optional) is the name of the global objects(s) to be copied from 


the designated stored workspace. If this parameter is omitted, all global 
objects in the designated stored workspace are copied. 
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The )DROP Command 


The )DROP command marks a specified file unused. After the file has been 
marked unused, the data in the file can no longer be read from the media. 
Once the file is marked unused, the file is available to be used in the same 
manner as a newly formatted file (see The )MARK Command). When the 
command is successfully completed, DROPPED device/file number file ID is 
displayed. 


Note: For diskette files, the )FREE command must be used if the diskette file 


space is to be reallocated to another file (see The )FREE Command in this 
chapter). 


Syntax 
)DROP_ [device/file number] [file ID] 


Where: 


device /file number (optional for diskette only) is the number of the device 
and the file on the media. 


file ID is the name of the file to be marked unused. This parameter is 
required for all APL stored workspace files and is optional for data files if 
the device/file number is specified. The name specified by this parameter 
is compared to the media file ID. If the names do not match, the error 
message FILE NOT FOUND is displayed. 


Note: When a diskette file is dropped, the diskette file name is not changed. 


The )JERASE Command 


The )ERASE command erases the named global objects from the active 
workspace. No message is displayed after the successful completion of the 
command. 


Notes: 

1. When a pendent function is erased, the response SI DAMAGE is issued. 

2. If the object being erased is a shared variable (see Chapter 7), the shared 
variable will be retracted. 

3. Even after the object is erased, the name remains in the symbol table (the 
part of the active workspace that contains all the symbols used). 


Syntax 
JERASE object name(s) 
Where: 


object name(s) are global names separated by blanks. 


The )FILEID Command 


The )FILEID command is used to change or display the file name on a diskette 
volume. When the )FILEID command is issued without specifying a new file 
name, device file number file name is displayed. When the )FILEID command 
is issued specifying a new file name, WAS device/file number file name is 
displayed and the file name is changed to the new file name. 


Syntax 


)FILEID [device/file number] [current file name] [new file name] 


Where: 


device/file number (optional) is an integer that specifies the device/file 
number. 


current file name (optional) is the current name of the file. This parameter is 
optional only if the device/file number is specified and a new name is not 
specified. 


new file name (optional) will be the new name for the file. 


The )FNS Command 


The )FNS command displays the names of all global user-defined functions in 
the active workspace. The functions are listed alphabetically. If the character 
parameter is specified, the names are displayed beginning with the specified 
character or character sequence. 


Note: You can interrupt the )FNS command by pressing the ATTN key. 


Syntax 
)FNS_[character(s) ] 
Where: 


character(s) (optional) is any sequence of alphabetic and numeric characters 
that starts with an alphabetic character and contains no blanks. This 
sequence of characters determines the starting point for an alphabetic 
listing. 
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The )FREE Command 
The )FREE command makes diskette files available for reallocation. After the 
file is made available for reallocation, the space can be used for other 
numbered files by the )MARK command. 
When the command is successfully completed, FREED device/file number file 
ID is displayed. 

Syntax 
)FREE [device/file number] file ID 


Where: 


device/file number (optional) is an integer that specifies the diskette device/file 
number where the diskette file is stored. 


file ID is the name of the stored file. This parameter must be specified for APL 
workspace files. For data files, this parameter is optional if the device/file 
number is specified. 


The )LIB Command 


The )LIB command displays the file headers of the files on tape or diskette. 


The file header contains the following information: 


File number. 


File ID. The file ID can be from 1 to 17 characters. If the file contains a 
stored workspace, the file ID is the same as the stored workspace ID. 


File type. The file type is a two-digit code; the following chart gives the 
meaning of each code: 


File Type 


Description 


Unused file 

Sequential access—exchange data file 

Sequential access—general exchange data file 
BASIC source file 

BASIC workspace file 

BASIC keys file 

APL continued file-5100 only 

APL saved file 

Sequential access--APL internal format data file 
Direct access—exchange, general exchange, and 
unblocked/unspanned data file 

Direct access—unblocked/unspanned data file that can be 
used for exchanging data with other products 
Direct access—APL internal format data file 

BASIC source file-5110 only 

BASIC keys file-5110 only 

Direct access—APL mixed record data file 

Patch, tape recovery, and tape copy file—5100 onty 
Diagnostic file—5100 only 

Communications file-5100 only 

IMF file-5100 only 

Patch, tape recovery, and tape copy file—5110 only 
Feature file-5110 only 

IMF file—5110 only 

Diagnostic file-5110 only 

APL continued file—5110 only 

Storage dump—tape only 
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Size of the file. The files are formatted in increments of 1024-byte blocks 


of storage. 


Number of unused contiguous 1024-byte blocks of storage in the file. 
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e (Tape only) Number of defective records (512-byte blocks) in the file; an 
asterisk (*) is displayed if there are more than nine defective records. 


Note: This value can indicate when you should relocate a file to avoid loss 
of data due to defective areas on the tape. 


¢ (Diskette only) Write-protect indicator; a P indicates that the file is 
write~protected. That is, you cannot write data to the file. Otherwise, this 
position is blank. 

« (Diskette only) Starting location of the first record in the file. This hex value 
is in the format CCHRR, where CC is the cylinder number, H is the head 


number, and RR is the sector number. 


Following is an example of a tape file header: 


006 FILES O07 010,001 0 


File a 


Size of the File 


Available Storage 
Number of Defective Records 
File ID 

File Number 


Following is an example of a diskette file header: 


0023 FILELS eo& O020, 0007 P 191.04 


File | 


Size of the File 

Available Storage 

Write Protect Indicator 
Starting Location (CCHRR) 
File 1D 

File Number 


You can interrupt the )LIB command operation by pressing the ATTN key. 


Page of SA21-9303-0 
Issued 28 April 1978 
By TNL: SN21-0284 


Syntax 
)LIB_ [device/file number ] 
Where: 


device/file number (optional) is the number of the device and starting file 
number. All file headers from that file to the end of the media are 
displayed. If this parameter is not specified, the default device is assumed 
and: 


e For the 5110 Model 1, the display begins with the first file following the 
file you are currently positioned at on tape unit 1 


« For the 5110 Model 2, the display begins with the first file on diskette 
drive 1 


For the tape units, the device number followed by O00 displays the file 
headers beginning with. the first file you are currently positioned at on the 
tape unit. For example, 2000 specifies tape unit 2. 


For diskette drives, the device number followed by O00 displays the file 
headers beginning with the first file on the diskette drive. 


Note: For diskette files, only the file headers of the formatted files (see The 
)MARK Command) are displayed. 


The )LINK Command 


The )LINK command is used to load special programs (file type 21 only), such 
as asynchronous communications or customer support functions, into the 5110. 


Syntax 
)LINK [device/file number] [file ID] 
Where: 


device/file number (optional for diskette only) is the number of the device 
and the number of the file that contains the microcoded programs. 


file ID (optional) is the name of the file that contains the microcode 
programs. This parameter is optional on diskette only if the device/file 
number is specified. 


Note: If an I/O error or workspace full condition occurs when you are using 
the )LINK command, the program is not loaded and the CLEAR WS message 
is displayed. In this case, you should press RESTART to clear any IMFs 
(internal machine fixes), storage allocated for procedure files, or other special 
programs from the active workspace. Then try the )LINK command again. If 
the program loads successfully, you must also reload any required IMFs. If the 
program still does not load, call your service representative. 
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The )LOAD Command 


The )LOAD command loads the contents of a stored workspace from the tape 
or diskette into the active workspace, completely replacing the contents that 
were in the active workspace. When the command is successfully completed, 
LOADED device/file number workspace ID is displayed. 


Notes: 

1. If the ATTN key is pressed during a load operation, the system operation is 
interrupted and the active workspace is cleared. 

2. Any shared variables that were established when the stored workspace was 
written to the media are not automatically reestablished during a load 
operation. (See The )RESUME Command for information on reestablishing 
shared variables when a stored workspace was written to the media by the 
JCONTINUE command.) 

3. The system does not successfully terminate current. input/output operations 
(see Chapter 7) when a )LOAD command is issued. Therefore, if a new data 
file is being created or if records are being added to an existing data file 
and a )LOAD command is issued without terminating the operation, the file 
header is not updated and the file contents are unpredictable. 

4. If the stored workspace contains a latent expression (see the LX system 
variable in Chapter 5), the latent expression is always executed when the 
)LOAD command is issued. 


Syntax 
)LOAD [device/file number] [workspace ID] :password 
Where: 


device/file number (optional for diskette only) is the number of the device 
and the number of the file on the media. 


workspace ID (optional) is the name of the stored workspace. This 
parameter is optional only if the device/file number is specified. 


:password is the security password assigned to the stored workspace by a 
previous )WSID, )CONTINUE, or )SAVE command. If no password was 
previously assigned, a password cannot be specified. If a password was 
assigned to the stored workspace but is not specified, or if it is incorrectly 
specified for this command, the error message WS LOCKED is displayed. 
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The MARK Command 


The )MARK command formats the media so that the active workspace or data 
can be saved on it. Each )MARK command formats a specified number of files 
to a specified size. Additional files of different sizes can be formatted by 
additional J)MARK commands. 


When the operation is successfully completed, MARKED number of the last 
file marked size of the last file marked is displayed. 


Notes: 


1. 
2. 


Syntax 


The ATTN key is not operative during the MARK command operation. 

If the message ALREADY MARKED is displayed after a JMARK command 
has been issued, the specified file already exists on the media. To re-mark 
the specified file, enter GO. If the file is not to be re-marked, press 
EXECUTE to continue. 


CAUTION 

If an existing file on tape is re-marked, the original information in the 
re-marked file and the existing files following the re-marked file cannot be 
used again. 


. (Diskette only) The files within the range specified by the )MARK command 


are the only files on the diskette that are affected. 


. (Diskette only) The user can control the location of a file on the diskette 


only by using a totally unformatted diskette and issuing )MARK commands 
in the same order as the files that are to be formatted on the diskette. 


. (Diskette only) If a size of zero is specified, the files within the range 


specified by the )MARK command are made available for reallocation. After 
the file is made available for reallocation, the diskette space can be used for 
other numbered files by the MARK command. 


. (Diskette only) The maximum number of files allowed on a diskette is 19 for 


a diskette type 1; 45 for a diskette type 2: 71 for a diskette type 2D (unless 
the diskette initialization function was used to get additional file headers: 
see the IBM 5110 Customer Support Functions Reference Manual, 
$A21-9311). 


)MARK size number of files to mark starting file number [device] 


Where: 


size is an integer specifying the size of each file in 1024-byte (1K) blocks of 
storage. 
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The following formulas can be used to determine the maximum size the file 
must be marked. The formula for a workspace file (the contents of the 
active workspace written to tape with a SAVE or )CONTINUE command) is: 


MAXSIZE=3+[f (CLEAR-ACTIVE) + 1024 
where: 


» MAXSIZE is the maximum amount of media storage (number of 
1024-byte blocks) that might be required to write the contents of the 
active workspace to the media. 


» CLEAR is the value of WA (see Chapter 5) in a clear workspace. 


» ACTIVE is the value of DWA just before the contents of the active 
workspace are written to the media. 


The amount of storage actually required can vary considerably between 
different workspaces because of their content, if they are on tape or 
diskette, or if they were written with a )SAVE or )JCONTINUE command. 


The formula for a data file (data written to the media with an APL shared 
variable~see Chapter 7) when all of the data is contained in the active 
workspace is: 


MAXSIZE=[ (without-with) + 1024 
where: 


« MAXSIZE is the maximum amount of media storage (number of 
1024-byte blocks) required to write the data to the media. 


« WITH is the value of JWA (see Chapter 5) with the data in the active 
workspace. 


« WITHOUT is the value of DWA before any data to be written to the 
media was stored in the active workspace. 


There is no formula for determining what size to mark a data file when the 
data is written to the media as it is entered from the keyboard. The amount 
of media storage required depends upon how much data is entered from the 
keyboard and what type of data is used. For information on how many 
bytes of storage are required by the various types of data, see Storage 
Considerations in Chapter 2. 


Note: The file header for each marked tape file requires 0.5K bytes of 
storage. Therefore, the number of bytes of tape storage required for each 
file is the specified size of the file plus 0.5K. 


number of files to mark is an integer specifying the number of files of the 
specified size to format. 


starting file number is an integer specifying the file number where formatting 
is to start. 


device (optional) specifies the device that contains the media to be 
formatted. An entry of 1 specifies tape unit 1, 2 specifies tape unit 2, 11 
specifies diskette drive 1, and 12 specifies diskette drive 2. If no entry is 
made, the default device is used. 


To format a tape for four 12K files, two 16K files, and three 10K files, the 
following commands are required: 


)MARK 12 4 1 
JMARK 16 2 5 Starting File Number 
)MARK 10 3 7 


To format a diskette on diskette drive 1 for four 12K files, two 20K files, and 
one 10K file, the following commands are required: 


)MARK 12 4 1 11 
)MARK 20 2 5 11 Device 11 (diskette drive 1) 


)MARK 10. 1 7 11 


The )OUTSEL Command 
The )OUTSEL command specifies which data on the display will go to the 
printer. 
Syntax 
JOUTSEL [option] 
Where: 
option is one of the following: 


* When ALL is specified, all subsequent information that is displayed will 
be printed. 


¢ When OUT is specified, only the output is sent to the printer; input is 
displayed, but it does not go to the printer. 


« When OFF is specified, none of the information displayed is printed, 
unless it is assigned to an APL shared variable used by the printer (see 


Chapter 7). 


If no parameter is specified, ALL is assumed. After a )LOAD or )CLEAR 
command or when the machine is first turned on, the ALL option is active. 
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The )PCOPY Command 


The )PCOPY command copies all or specified global objects from a stored 
workspace into the active workspace. It is the same as the )COPY command, 
except that if the object name already exists in the active workspace, it is not 
copied from a stored workspace. Therefore, the object in the active workspace 
is protected from being overlaid and destroyed. Only objects in stored 
workspaces that were written on the media with the )SAVE command can be 
copied. 


When the command is successfully completed, COPIED device/file number 
workspace ID is displayed. 


Notes: 


1. 


2. 


Syntax 


If the active workspace contains suspended functions, objects cannot be 
copied into it. 

if the ATTN key is pressed during a )PCOPY operation, the system 
operation is interrupted and the amount of information copied into the active 
workspace is unpredictable. 


. If the specified object name already exists in the active workspace, the 


message NOT COPIED: object name is also displayed. 


)PCOPY [device/file number] [workspace ID] :password [object name(s) ] 


Where: 


device/file number (optional for diskette only) is the number of the device 
and the stored workspace file. 


workspace ID (optional) is the name of the stored workspace on the media. 
This parameter is optional only if the device/file number is specified. 


:password is the security password assigned by the previous )WSID or 
)SAVE command. If no password was assigned, a password cannot be 
specified by this command. 


object name(s) (optional) is the name of the global object(s) to be copied 
from the designated stored workspace. If omitted, all global objects in the 
designated stored workspace are copied, except those already in the active 
workspace (if any). 


The )PROC Command 


The )PROC command opens an external procedure file that is used by the 5110 
as an alternative to keyboard input (see Chapter 2). A procedure file contains 
character records that represent any input that is possible to enter from the 
keyboard, such as system commands, function definitions, or APL statements. 


When a )PROC command is issued, all input comes from the procedure file 
until the end-of-data is reached. Then the 5110 goes back to using regular 
keyboard input. 


Notes: 

1. The )PROC command requires 768 bytes from the active workspace. This 
space can be allocated only in a CLEAR WS; therefore, the active 
workspace is always cleared the first time a )PROC command is issued. The 
active workspace is not cleared for any subsequent )PROC commands 
because the 768 bytes are already allocated. 

2. You can establish the 768 bytes of active workspace by issuing the )PROC 
command without any parameters. This allows you to clear the active 
workspace, establish the 768-byte area required by the PROC command, 
use the active workspace for any APL operations, and issue subsequent 
)PROC commands when you are ready to execute statements from a 
procedure file. 


Syntax 
)PROC [device/file number] [file ID] 


Where: 


device/file number (optional for diskette only) is an integer that specifies the 
device/file number where the procedure file is stored. 


file ID (optional) is the name of the procedure file. This parameter is 
optional only if the device/file number is specified. 
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The )JPROTECT Command 


The )PROTECT command invokes or removes the write-protect indicator on a 
diskette file. When the write-protect indicator is on for a specified diskette 
file, you cannot write to that diskette file. This will prevent someone from 
writing data to a diskette file accidently. 


Syntax 
)PROTECT [device/file number] [file 1D] [OFF/ON] 


Where: 


device/file number (optional) is an integer that specifies the device/file 
number where the write-protect indicator is invoked or removed. 


file ID (optional) is the name of the diskette file. This parameter is optional 
only if the device/file number is specified. 


OFF /ON (optional) specifies whether the write-protect indicator is to be 
removed (OFF) or invoked (ON). This parameter can be used only when the 
file ID is specified. If this parameter is not specified, the write-protect 
indicator is invoked. 


The )RESUME Command 


The )RESUME command loads the contents of a workspace that was stored by 
the )CONTINUE command into the active workspace and attempts to 
reestablish the system's environment as it was when the workspace was 
stored. 


This includes reestablishing shared variables and reestablishing suspended 
functions. For shared variables, an attempt is made to reestablish the shared 
variables as follows: 


-« Diskette data files are checked to make sure they are on the proper diskette 
drive. If the data files are not on the proper diskette drive, a WRONG 
VOLUME error message is displayed. However, the stored workspace is 
still loaded into the active workspace. 


If the WRONG VOLUME error message is displayed, place the diskette 
containing the correct data files in the proper diskette drive before doing 
any input/output. 


CAUTION 
If the correct diskette is not placed in the proper diskette drive, data on the 
diskette presently in the diskette drive can be overwritten and lost. 


e Tape files are not checked. It is assumed that all tapes remain in the correct 
position and are mounted on the correct devices. If the wrong tape is 
placed in the tape drive or if the tape has been repositioned, it is possible to 
overwrite in the wrong location. 


« Any shared variables to the printer are reestablished. 

« Any shared variables to attached serial |/O devices are reestablished; 
however, you are responsible for establishing the correct serial |/O 
environment (such as making sure the serial |/O devices are attached) 
before issuing the JRESUME command. 

When the )JRESUME command is used, the latent expression (UJLX) is not 

executed and )OUTSEL ALL is assumed unless a shared variable to the printer 

was specified. When the command is successfully completed, RESUMED 
device/file number workspace ID is displayed. 
Syntax 
)JRESUME [device/file number] [workspace ID] :password 
Where: 


device/file number (optional) is the number of the device and file number of 
the stored workspace. 


workspace ID (optional) is the name of the stored workspace. This 
parameter is optional only if the device/file number is specified. 
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:password is the security password assigned to the stored workspace by a 
previous )WSID or )JCONTINUE command. If no password was previously 
assigned, a password cannot be specified. If a password was assigned to 
the stored workspace but is not specified, or if it is specified incorrectly for 
this command, the error message WS LOCKED is displayed. 


The )JREWIND Command 


The )REWIND command rewinds the specified tape. No message is displayed 
at the successful completion of this command. 


Syntax 
JREWIND [device number ] 
Where: 


device number (optional) is the tape (on drive 1 or 2) to be rewound. If this 
parameter is omitted, tape 1 is rewound. 


The )SAVE Command 


The )SAVE command stores the contents of the active workspace onto the 
media without changing the contents of the active workspace. Individual global 
objects can be copied from the stored workspace to the active workspace. 
When this command is successfully completed, SAVE device/file number 
workspace ID is displayed. Do not remove the tape or diskette until this 
message is displayed. 


Notes: 

1. A clear workspace or a workspace with suspended function cannot be 
written to the media by the )SAVE command; however, a workspace with 
suspended functions can be written to the media by the )JCONTINUE 
command. 

2. The )COPY and )PCOPY commands can specify stored workspaces that 
were written on the media only if the )SAVE command was used. 

3. Depending on the amount of data in the stored workspace, a stored 
workspace that was written to the media by the )SAVE command can be 
loaded into another 5110 with a smaller active workspace. 

4. If ATTN is pressed during a )SAVE operation, the system operation is 
interrupted and file is set to unused. 

5. Shared variables cannot automatically be reestablished in the active 
workspace when the workspace is stored on the media by the )SAVE 
command. However, the shared variable can be automatically reestablished 
in the active workspace when the workspace is stored by the JCONTINUE 
command. 

6. IMFs (internal machine fixes) are not stored by the )SAVE operation. If an 
IMF is required, it is necessary to use the )LINK command to reload the IMF 
(if the IMF is not already in the system) before the stored workspace is 
reloaded. 

7. Only workspaces stored on the media by the )SAVE command can be 
interchanged between the 5110 and the 5100. 


Syntax 
~ )SAVE [device/file number] [workspace ID] [ :password ] 
Where: 


device/file number (optional) is the number of the device and the file on the 
tape or diskette where the contents of the active workspace are to be 
written. If no device/file number is specified, the device/file number from 
which the active workspace was loaded or which was specified by a 
previous )WSID command is used. 


workspace ID (optional) is the name of the workspace to be stored. This 
name must match the workspace ID of both the active workspace and the 
file to be used on the media unless the file is mark unused. If the file is 
marked unused, the active workspace and file workspace !D will be changed 
to this workspace ID. If no name is specified in the command, the name of 
the active workspace is used. 


:password (optional) is any combination of up to 8 alphabetic or numeric 
characters (without blanks), preceded by a colon. This sequence of 
characters must be matched when the stored workspace is to be read back 
into the active workspace. If no workspace ID or password is entered, the 
password associated with the active workspace (if any) is assigned to the 
workspace being stored. If just the workspace ID and no password is 
entered, any password associated with the active workspace is not used. 


The )S!| Command 
The )SI command displays the names of the suspended and pendent 
user-defined functions. The suspended functions are indicated by an *, with 
the most recently suspended function listed first, followed by the next most 
recently suspended function, and so on. 

Syntax 


)SI 


There are no parameters. 


The )SINL Command 
The )SINL command displays the names of the suspended and pendent 
user-defined functions and the names local to each function. The suspended 
functions are indicated by an *, with the most recently suspended function 
listed first, followed by the next most recently suspended function, and so on. 
Syntax 
)SINL 


There are no parameters. 
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The )SORT Command 


The )SORT command transfers system control to the sort feature (see the 
5110 Customer Support Functions Reference Manual, SA21-9311, for a 
complete description of the sort feature). 


Note: If the /SORT command is issued from a procedure file (see The )PROC 
Command), the statement immediately following the )SORT command 
statement is used as the initial input to the sort feature. When the sort feature 
is complete, the 5110 continues to take input from the procedure file. 


Syntax 
)SORT 


There are no parameters. 


The )SYMBOLS Command 


The )SYMBOLS command is used to change or display the number of symbols 
(variable names, function names, and labels) allowed in the active workspace. 
The number of symbols allowed can only be changed immediately after a 
)CLEAR command has been issued. In a clear workspace, the number of 
symbols allowed is initially set to 125 by the 5110. When the command is 
used to display the number of symbols allowed, IS the number of symbols 
allowed, number of symbols used IN USE is displayed. When the command is 
used to change the number of symbols allowed, WAS the former number of 
symbols allowed is displayed. 


Note: When a stored workspace is loaded into the active workspace, the 
number of symbols allowed in the active workspace will be the same as when 
the stored workspace was written to the media. 


Syntax 
SYMBOLS [n] 
Where: 


n (optional) is an integer equal to or greater than 26 that specifies the 
number of symbols allowed in the active workspace. Each symbol allowed 
requires 8 bytes of storage in the active workspace. 


Notes: 

1. The number of symbols allowed is assigned in blocks of 21; therefore, the 
actual number allowed can be larger than the number specified. 

2. When a symbol is used in the active workspace, it remains in use even 
though the object is erased or, in the case of VALUE ERROR never existed. 
When the active workspace is written to tape with the )SAVE command and 
subsequently reloaded, these unused names are removed from the symbol 
table, and the number of symbols in use will be the same as the number of 
objects in the workspace. 

3. The total number of allowed symbols remains the same after you write the 
workspace to the media with a )SAVE or )JCONTINUE command and then 
reload the workspace to the active workspace. The number of symbols in 
the active workspace can be changed as follows: 

a. Save the active workspace with the )SAVE command. 
b. Clear the active workspace with the )CLEAR command. 

c. Set the new number of symbols with the SYMBOLS ath th COPY 
d. Copy the stored workspace to the active workspace with thé )COPY a 
command. ais 

e. The workspace ID and [JLX must be respecified. 


The )VARS Command 
The )VARS command displays the names of all global variables in the active 
workspace. The variables are displayed alphabetically. If the character 
parameter is included, the names are displayed beginning with the specified 
character sequence. 

Syntax 
VARS _[ character(s) ] 
Where: 

character(s) (optional) is any sequence of alphabetic and numeric characters 


that starts with an alphabetic character and contains no blanks. This entry 
can be used to define the starting point for an alphabetic listing. 
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The )VOLID Command 


The )VOLID (volume ID) command is used to change or display the volume ID 

or change the access-protect indicator of a diskette device. When the )VOLID 

command is issued without any parameters, volume [D owner ID record size is 
displayed. When the )VOLID command is issued with parameters, 

WAS volume ID owner ID record size is displayed. 


Note: The record size cannot be changed by the )VOLID command. 


Syntax 


)VOLID [device number] [volume ID] [owner ID] [access-protect indicator ] 


Where: 
device number (optional) is the number of the diskette device. 


volume ID (optional) will be the new identifier for the diskette volume. This 
parameter can be up to 6 alphabetic and numeric characters. 


owner ID (optional) is the new identifier for the owner of the diskette 
volume. This parameter can be up to 14 alphabetic and numeric characters. 
If this parameter is not specified, the owner ID is not changed. 


access-protect indicator (optional) is specified as either ON or OFF. This 
parameter can be specified only when the volume ID and owner ID 
parameters are also specified. The access-protect indicator prevents 
unauthorized access to the diskette volume; any attempt to access the 
diskette generates an ERROR 043 message. 


Following are examples of using the )VOLID command: 
)VOLID Displays the volume ID, owner ID, and 


record size of the diskette on diskette drive 
1. 


)VOLID 12 Displays the volume ID, owner ID, and 
record size of the diskette on diskette drive 
a 

)VOLID 11 NEW Changes the volume !D of the diskette on 


diskette drive 1 to NEW; the owner ID 
remains the same. 


)VOLID 11 NEW JOHN Changes the owner ID of the diskette on 
diskette drive 1 to JOHN; the volume ID is 
also changed if the volume ID was not 
already NEW. 


JVOLID 11 NEW JOHN ON Sets the access-protect indicator on for the 
diskette on diskette drive 1. 


The )WSID Command 


The )WSID (workspace ID) command is used to change or display the 
device/file number and workspace ID of the active workspace. The )WSID 
command is also used to change or assign the security password. If a )SAVE 
or )JCONTINUE command is specified without any parameters, the contents of 
the active workspace are written to the device and file number specified by the 
)WSID command. When the )WSID command is issued without any 
parameters, device/file number workspace ID is displayed. When the )WSID 
command is issued with parameters, WAS device/file number workspace ID is 
displayed. 


Note: The )WSID command affects only the active workspace; it cannot be 


used to change any information on tape or diskette. 


Syntax 
JWSID  [device/file number] [workspace ID] [ :password] 
Where: 


device/file number (optional) is an integer that specifies the device/file 
number where the active workspace will be stored when either the )SAVE or 
)CONTINUE command is issued. 


Note: If this parameter is omitted, the device/file number is cleared: a 
JSAVE or )JCONTINUE command will not work unless a device/file number 
is specified in that )SAVE or )JCONTINUE command. 


workspace ID (optional) will be the new name for the active workspace. This 
parameter must be entered if any other parameter is used. 


:password (optional) is any combination of up to 8 alphabetic or numeric 
characters (without blanks), preceded by a colon. These characters will 
become the security password for the tape file when the active workspace 
is written on tape. 
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Chapter 4. Primitive (Built-In) Functions 


APL functions are of two types: user-defined and built-in. User-defined 
functions are discussed in Chapter 6. Built-in functions, called primitive 
functions, are denoted by a symbol and operate on the data you supply to 
them. 


The value or values you supply are called arguments. Primitive functions that 
use two arguments, such as A+B, are said to be dyadic; functions that use 
one argument are said to be monadic, such as +B, which yields the reciprocal 
of B. Arguments can be single data items (scalars), strings of data (vectors), 
tables of data (matrices), or multiple tables of data (N-rank arrays). Arguments 
can also be expressions or user-defined functions that result in a scalar, 
vector, matrix, or N-rank array. 


There are two types of primitive functions: scalar functions and mixed 
functions. There are also operators that operate on the primitive functions. 
Examples of the functions and operators are provided throughout this chapter 
for easy reference and are set up as they would appear on the display. 


PRIMITIVE SCALAR FUNCTIONS 


Scalar functions operate on scalar arguments and arrays. They are extended to 
arrays element by element. The shape and rank of the result depend on the 
shape and rank of the arguments. For dyadic scalar functions, the relation 
between the types of arguments and the shape of the result is shown in the 
following table. Each scalar function is described following the table: 


Argument A Argument B 


Scalar Scalar Scalar 


Array Array with the same Array with the same 
shape as A shape as the 
arguments 


Scalar or one- Array of any Array with the 
element array shape same shape as 
argument B 


Array of Scalar or one- Array with the same 
any shape element array shape as argument A 


One-element One-element array One-element array 

array with the rank with the shape of 
different from the the array with the 
rank of A greater rank 


Primitive (Built-In) Functions 59 


60 


The + Function: Conjugate, Plus 
+ 


Monadic (One-Argument) Form: Conjugate +B 


The conjugate function does not change the argument. The argument can be a 
numeric scalar, vector, or other array, and the shape of the result is the same 
as that of the argument: 


If B is an array, the function is extended to each of the elements of B. The 
shape of the result is the shape of B: 


Bee ce oa ae OL a 
B 

“ae 

a ae 
a 

ee. | 
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Dyadic (Two-Argument) Form: Plus A+B 


The plus function results in the sum of the two arguments. The arguments can 
be numeric scalars, vectors, or other arrays. Arguments must be the same 
shape, unless one of the arguments is a scalar or single-element array. If the 
arguments have the same shape, the result has the same shape as the 


arguments: 
AS 
4 
Pe eS 
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c : fs + a ‘ +e 
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If one argument is a scalar or single-element array, the shape of the result is 
the same as that of the other input argument. The single element is applied to 
every element of the multielement array: 


Bee Sel 2 34 3G 
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The - Function: Negation, Minus 
+ 


Monadic (One-Argument) Form: Negation -B 


The negation function changes the sign of the argument. The argument can be 
a numeric scalar, vector, or other array. The shape of the result is the same as 
that of the argument: 


Ae") 7S 
A 
1 “3 
fy 
1 3 
If the argument is an array, the function is extended to each element of the 
array. 
Be? Be "S "2 “1 0 1 2 
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Dyadic (Two-Argument) Form: Minus A-B 


The minus function subtracts argument B from argument A. The arguments 
can be numeric scalars, vectors, or other arrays. The arguments must be the 
same shape unless one of the arguments is a scalar or any single-element 
array. If the arguments are the same shape, the result has the same shape as 
the arguments: 


hf “hy 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other input argument. The single element is applied to 
every element of the multielement array: 
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The x Function: Signum, Times 
x 


Monadic (One-Argument) Form: Signum xB 


The signum function indicates the sign of the argument. If the argument is 
negative, 1 is the result; if the argument is zero, then O is the result; if the 
argument is positive, 1 is the result. The argument can be a numeric scalar, 
vector, or other array. The shape of the result is the same as that of the 
argument: 


x"25 0 33 
a A 


If the argument is an array, the function is extended to each of the elements: 


2 it @ 
EY tie tee 
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Dyadic (Two-Argument) Form: Times AXB 


The times function result is the product of argument A times argument B. The 
arguments can be numeric scalars, vectors, or other arrays. The arguments 
must be the same shape, unless one of the arguments is a scalar or any 
single-element array. Arguments of the same shape have the same shape 


result: 


lf one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other input argument. The single element is applied to 


every element of the multielement array: 
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The + Function: Reciprocal, Divide 
x 


Monadic (One-Argument) Form: Reciprocal +B 


The reciprocal function result is the reciprocal of the argument. The argument 
can be a numeric scalar, vector, or other array. The shape of the result is the 
same as that of the argument: 


lf the argument is an array, the function is extended to each of the elements: 


BE? 2p2 3 
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Dyadic (Two-Argument) Form: Divide A+B 


The divide function result is the quotient when argument A is divided by 
argument B. The arguments can be numeric scalars, vectors, or other arrays. 
The arguments must be the same shape unless one of the arguments is a 
scalar or a single-element array. Arguments of the same shape have the same 
shape result: 


S73 


«2 t: ae 
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If one argument is a scalar:or a single-element array, the shape of the result is 
the same as that of the other input argument. The single element is applied to 
every element of the multielement array: 


Ree 2e] 10 20 100 


3, 
1 10 
20 106 
a 0.3 
O.15 0.03 


Note: There are two additional rules that apply to the divide function: 
y When zero is divided by zero, the result is 1: 


+0 
1 


2. Any value other than zero cannot be divided by zero: 


30 
QNOMAIN ERROR 
3-0 
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The [ Function: Ceiling, Maximum 
S 


Monadic (One-Argument) Form: Ceiling [B 


The ceiling function result is the next integer larger than the argument (the 
argument is rounded up), unless the argument already is an integer. In this 
case, the result is the same as the argument. The argument can be a numeric 


scalar, vector, or other array. The shape of the result is the same as that of 
the argument: 
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If the argument is an array, the function is extended to each of the elements: 


Bee 2p kDa: ack ae 


jae 

2 
Note: The result of the ceiling function depends on the ICT system variable 
(see Chapter 5 for information on the OCT system variable). 


Dyadic (Two-Argument) Form: Maximum AT B 


The maximum function result is the larger of the arguments. The arguments 
can be numeric scalars, vectors, or other arrays. The arguments must be the 
same shape unless one of the arguments is a scalar or any single-element 
array. Arguments of the same shape have the same shape result: 


Wl & 
4 
42 
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If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 
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The L Function: Floor, Minimum 
D 


Monadic (One-Argument) Form: Floor LB 


The floor function result is the next integer smaller than the argument (the 
argument is rounded down) unless the argument is already an integer. In this 
case, the result is the same as the argument. The argument can be a numeric 


scalar, vector, or other array. The shape of the result is the same as that of 
the argument:. 


Le ee 


I. Ly. 


If the argument is an array, the function is extended to each of the elements: 


hed? Pel 1.5 1.6 2 
R 
Leo 
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Note: The result of the floor function depends on the IICT system variable 
(see Chapter 5 for information on the ICT system variable). 


Dyadic (Two-Argument) Form: Minimum ALB 


The minimum function result is the smaller of the arguments. The arguments 
can be numeric scalars, vectors, or other arrays. The arguments must be the 
same shape unless one of the arguments is a scalar or any single-element 
array. Arguments of the same shape have the same shape result: 


Wh} 
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If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


he? Sel 2 3 4 3 6} 
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The | Function: Magnitude, Residue ie 


Monadic (One-Argument) Form: Magnitude |B 
The magnitude function result is the absolute value of the argument. The 
argument can be a numeric scalar, vector, or other array. The shape of the 
result is the same as that of the argument: — 
rao 
3 
If the argument is an array, the function is extended to each of the elements: 


Be? 2evS.) “1 0 3.14 
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Dyadic (Two-Argument) Form: Residue A|B 


The residue function result (when both argument A and argument B are 
positive) is the remainder when argument B is divided by argument A. The 
following rules apply when using the residue function: 


1. If argument A is equal to zero, then the result is equal to argument B: 
Q14 
& 
2. If argument A is not equal to zero, then the result is a value between 


argument A and zero (the result can be equal to zero, but not equal to 
argument A). The result is obtained as follows: 


a. When argument B is positive, the absolute value of argument A is 
subtracted from argument B until a value between argument A and 
zero is reached: 


b. When argument B is negative, the absolute value of argument A is 
added to argument B until a value between argument A and zero is 
reached: 


The arguments can be numeric scalars, vectors, or other arrays. The 
arguments must be the same shape, unless one of the arguments is a scalar or 
any single-element array. Arguments of the same shape have the same shape 


result: 
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If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 
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The * Function: Exponential, Power 
Pp 


Monadic (One-Argument) Form: Exponential *B 


The exponential function result is the Naperian base e (2.718281828459045) 
raised to the power indicated by the argument. The argument can be a 


numeric scalar, vector, or other array. The shape of the result is the same as 
that of the argument: 
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If the argument is an array, the function is extended to each element of the 


array: 
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Dyadic (Two-Argument) Form: Power AxB 


The power function result is argument A raised to the power indicated by 
argument B. The arguments can be numeric scalars, vectors, or other arrays. 
The arguments must be the same shape unless one of the arguments is a 
scalar, or any single-element array. Arguments of the same shape have the 
same shape result: 
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To find the root of a number, you raise the number to the power indicated by 
the reciprocal of the root. For example, to find the square root: 


14 9 Léeee 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 
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The @ Function: Natural Log, Logarithm 
| P 


You form the ® symbol by overstriking the O symbol and the * symbol. 


Monadic (One-Argument) Form: Natural Log ®B 
The natural log function result is the log of the argument B to the Naperian 
base 6 (2.718281828459045). The argument can be a nonnegative numeric 
scalar, vector, or other array. The shape of the result is the same as that of 
the argument: 
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If the argument is an array, the function is extended to each element of the 


array: 
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Dyadic (Two-Argument) Form: Logarithm A®B 


The logarithm function result is the log of argument B to the base of argument 
A. The arguments can be numeric scalars, vectors, or other arrays. The 
arguments must be the same shape, unless one of the arguments is a scalar or 
any single-element array. Arguments of the same shape have the same shape 
result: 
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if one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Re? Bel 2 3 4 


B 
Loe 
3 Mt 
1LQak 
0 0.30103 
O41 2 1.40206 


The © Function: Pi Times, Circular 


Monadic (One-Argument) Form: Pi Times OB 


The pi times function result is the value of pi (3.141592653589793) times B. 
The argument can be a numeric scalar, vector, or other array. The shape of the 
result is the same as that of the argument. 
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lf the argument is an array, the function is extended to each element of the 


array: 
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Dyadic (Two-Argument) Form: Circular AOB 


The circular function result is the value of the specified trigonometric function 
(argument A) for the specified radians (argument B). The arguments can be 
numeric scalars, vectors, or other arrays. Arguments must be the same shape, 
unless one is a scalar or single-element array. Arguments of the same shape 
have the same shape result. The following is a list of the values for the A 
argument and the related functions performed. A negative argument A is the 
mathematical inverse of a positive argument A; any values for argument A 
other than the following will result in DOMAIN ERROR: 


Value of A Operation Performed 
00B (1-B*2)*x.5———___. ! 
10B Sine B B 
20B Cosine B 
30B Tangent B 
40B (1+B x2) s——_Y | 
50B Hyperbolic sine of B (sinh B) : 
60B Hyperbolic cosine of B (cosh B) 
70B Hyperbolic tangent of B (tanh B) 
~10B Arcsin B 
~20B Arccos B 
~30B Arctan B 
“40B (~ 14+B x2) «.5 ———____ B 
“BoB Arcsinh B | j 
~6OB Arccosh B 
“JOB Arctanh B 
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If B is 45°, here is how to solve for the sine, cosine, and tangent of B (45° is 
equivalent to pi radians divided by 4): 


fie Oey 
Ii The left argument specifies 
0.7854 (~~ the trigonometric function. 
oR 
0.70714 Sine of B 
Os 
0.70711 Cosine of B 
SOK 


.-—_——_—_—_—_——__——____—___— Tangent of B 


If B is the sine of an angle, then OOB yields the cosine of the same angle, and 
conversely, if B is the cosine, OOB yields the sine. Suppose you wanted the 
sine of 30°, which is equivalent to pi divided by 6: 


Re LOCO+86) 
i 
0.5<————————— Sine of 30° 
Nok 
0.846603 -————Cosine of 30° 
he Po CO+ 4 3 
ik 
0.864603 ~-—————————-Cosine of 30° 
Oo 


0.53—————————____———— Sine of 30° 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Ae? Sel 2 3 


8} fo Cp Up. 
3) 
12 
“A OAL 
i 
0. 7554 
AOQK 
0, 70711 0.70711 
1 L.2716 


The ! Function: Factorial, Binomial @ a 


You form the ! symbol by overstriking the quotation mark (') and the period 


(.). 


Monadic (One-Argument) Form: Factorial !B 


The factorial function result is the product of all the positive integers from one 
to the number value of the argument. The argument can be a positive numeric 


scalar, vector, or other array. The shape of the result is the same as that of 
the argument: 


wy 
LxXOx xy 
ear 


fl 2 3 & S 
126 24 120 


The factorial function also works with decimal numbers and zero, but negative 
integers are not allowed. When used in this way, factorial can be defined by 
use of the mathematical gamma function—(! A) is equal to gamma (A+1): 


| 3 t 1 I. 
7.1733 
Ij 
L 
If the argument is an array, the function is extended to each of the elements: 


Bee 2e0 1 2 3 
B 


2 & 
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Dyadic (Two-Argument) Form: Binomial A!B 


The binomial function result is the number of different combinations of 
argument B that can be taken A at a time. The result of ASB is also the 
(A+1)*" coefficient of the binomial expansion of the Bt® power. The 
arguments can be numeric scalars, vectors, or other arrays. The arguments 
must be the same shape, unless one of the arguments is a scalar or any 
single-element array. Arguments of the same shape have the same shape 


result: 
atu 
& 
216 pw {x |y¥ |Z J+——Argument 8 
15 
3!0 
0 
O!3 The combinations of 
1 argument B taken 
O13 argument A(2) at a time 
3 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


0 1 2 33 
pet eae 
O37 2 3 GY 
14 6 4 I 
Be? 2e0 1 2 3 
I 


i ws 
10 10 
et SWS Yt 
10 10 7.875 6 


If noninteger arguments are used, this function relates to the beta function as 
follows: Beta (P,Q) is equal to +Q<(P-1)! P+Q-1 


The ? Function: Roll 


Monadic (One-Argument) Form: Roll ?B 


The roll function result is a randomly selected integer from O through B~1 or 1 
through B (depending on the index origin). Each integer in the range has an 
equal chance of being selected. The argument can be a positive integral scalar, 
vector, or other array. The shape of the result is the same as that of the 


If the argument is an array, the function is extended to each element of the 


argument: 
7300 
2Q2 
O300 
3 
a ee da 
ae | 
Yd & 
my 
74 6 
& & 
array: 
Be? Sell 
k 
Li @2 33 
bey SS 6G 
Oh 
§ 12 28 
2 3 3% 


Dyadic (Two-Argument) Form 


ee SS WE SS 6d 


‘oop 


See the deal function later in this chapter under Primitive Mixed Functions. 
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The A Function: And 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: And AAB 


The and function result is 1 when A and B are both 1; otherwise, the result is 
0. The value of the arguments must be either O or 1. The arguments can be 
scalars, vectors, or other arrays. The arguments must be the same shape, 
unless one of the arguments is a scalar or any single-~element array. 
Arguments of the same shape have the same shape result: 


And Table 
Qal 
0 Operator 
1. A |<— Argument A 
Lad 
0 
002 da0 1 023 


000 4 


te Argument B 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Bee 2e0 1 1 6 
ie 


Lak 


The VFunction: Or 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Or AVB 


The or function result is a 1 when either or both arguments are 1; otherwise, 
the result is 0. The values of the arguments must be 1 or 0. The arguments 
can be scalars, vectors, or other arrays. The arguments must be the same 
shape, unless one of the arguments is a scalar or any single-element array. 
Arguments of the same shape have the same shape result: 


Or Table 
Lvo 
1. Operator 
dvd 
0 <«—_——— Argument A 
002 iv0 1601 
04d. 


Argument B 


if one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Ree 2ed 1 0 od 
g 


Lvs 
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The ~ Function: Not 


Monadic (One-Argument) Form: Not ~B 


The not function result is 1 when B is O and O when B is 1. The values of the 
argument must be 1 or 0. The argument can be a scalar, vector, or other array. 
The shape of the result is the same as that of the argument: 


v () 
1 
vi 
0) 
If the argument is an array, the function is extended to each element of the 
array: 
Re? Sed 1 
kk 
0 it 0 
1 a4 
af 
1 04 
0 1 0 


Dyadic (Two-Argument) Form 


There is no dyadic form. 


The % Function: Nand 
(0) T 


_ You form the X symbol by overstriking the and (A) and the not (~) symbols. 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Nand AXB 


The nand function result is O when both A and B are 1; otherwise, the result is 
1. The values of the arguments must be 1 or 0. The arguments can be 
scalars, vectors, or other arrays. The arguments must be the same shape, 
unless one of the arguments is a scalar or any single-element array. 
Arguments of the same shape have the same shape result: 


Nand Table 


O%4 Operator —» A <—_————— Argument A 
1 

1X1 
0 

0041 14K0 1 Od 
111 0 


Argument B 
lf one argument is a scalar or a single-element array, the shape of the result is 


the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Be? 2ed 1 
ks 


148 
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The V Function: Nor 


You form the V symbol by overstriking the or (Vv) and the not (~) symbols. 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Nor AVB 


The nor function result is 1 when A and B are both O; otherwise, the result is 
0. The values of the arguments must be 1 or 0. The arguments can be 
scalars, vectors, or other arrays. The arguments must be the same shape, 
unless one of the arguments is a scalar or any single-element array. 
Arguments of the same shape have the same shape result: 


Nor Table 


190 Operator —» V + Argument A 
0 

070 
1 

001 190 1 O01 
100 0 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Bee 2ed 1 
is 
() 
0 J 


po 


ESS 5 
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The > Function: Greater Than 6 
Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Greater Than A>B 


The greater than function result is 1 when argument A is greater than argument 
B; otherwise, the result is O. The arguments can be numeric scalars, vectors, 
or other arrays. The arguments must be the same shape, unless one of the 
arguments is a scalar or any single-element array. Arguments of the same 
shape have the same shape result: 


1.5622 

“O29 
0 

“3272 
0 

0: “Uy, Y 
1 


1.42371.,.123 


“395.1 2 0 -4 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Re? Sel 2 Su SS Sb 
ft 

3 

& 
3:B 

0 

0 0 0 


aw. 
LA Po 


— 
a 


Notes: 

1. The result of the > function depends on the DCT system variable (see 
Chapter 5 for information on the OCT system variable). 

2. When the > function is used with logical data (see Chapter 2), a system 
error display can occur if the number of elements in the right argument is a 
multiple of 32. The following are examples: 
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| To prevent this error, separate the statement into two statements as 
| follows: 


First, assign the right argument for the > 
Aehe FO el function to a variable. 
Yeh 44d 


(SU5AIEY 


The = Function: Equal To (3) 


Monadic (One-Argument) Form 


‘Then, use the variable as the right argument 
ifor the > function. 


There is no monadic form. 


Dyadic (Two-Argument) Form: Equal To A=B 


The equal to function result is 1 when the value of argument A equals the value 
of argument B; otherwise, the result is 0. The arguments (numeric or 
character) can be scalars, vectors, or other arrays. The arguments must be the 
same shape, unless one of the arguments is a scalar or any other 
single-element array. Arguments of the same shape have the same shape 


result: 
0=5 
0 
1,654321=1,65432 
1 
t='A' 
0 
Ata Rt 
0) 
‘0 | 
5) 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


ate  ARACATAEAFAG' 
ee a ee He Oe 


- ees RS a | eee eed oS ee 
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Notes: . 
1. If the arguments are numeric, the result of the = function depends on the 
OCT system variable (see Chapter 5 for information on the OCT system 
variable). 
2. When the = function is used with logical data (see Chapter 2), a system 
error display can occur if the number of elements in the right argument is a 
multiple of 32. The following are examples: 


A&ke 70 oF 
CSU PAE LSU : 


To prevent this error, separate the statements as follows: 


First,, assign the right argument for the = 

ee eee function to a variable. 

(Ree FO ad 
Ye Bly Gul 


ee saa 


Then, use the variable as the right argument 
for the = function. 


The < Function: Less Than fs) 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Less Than A<B 


The less than function result is 1 when argument A is less than argument B; 
otherwise, the result is 0. The arguments can be numeric scalars, vectors, or 
other arrays. The arguments must be the same shape, unless one of the 
arguments is a scalar or any single-element array. Arguments of the same 
shape have the same shape result: 


1.6522 
l 

“ee 0 
Z 

aT: “+ 
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If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Be2 Sel 234 5 6 


LF to 
ea 


Ly 


So 
hm > 
fee] 


cr 
ore 


Notes: 


1. The result of the < function depends on the DICT system variable (see 
Chapter 5 for information on the DCT system variable). 

2. When the < function is used with logical data (see Chapter 2), a system 
error display can occur if the number of elements in the right argument is a 
multiple of 32. The following are examples: 


Daye RO od 


Pee FO od 


To prevent this error, separate the statement into two statements as 


follows: 
Year el 
Oy First, assign the right argument for the < 
function to a variable. 
Meee FO od 
Ye Rl Ghd Then, use the variable as the right argument 
CSU PAD AY for the < function. 


The > Function: Greater Than or Equal uo 
6 


Monadic (One-Argument) Form 


There is no monadic form. 
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Dyadic (Two-Argument) Form: Greater Than or Equal To A>B 


The greater than or equal to function result is 1 when argument A is greater 
than or equal to argument B; otherwise, the result is 0. The arguments can be 
numeric scalars, vectors, or other arrays. The arguments must be the same 
shape, unless one of the arguments is a scalar or any single-element array. 
Arguments of the same shape have the same shape result: 


1.6522 
0 
“2E0 
0 
222 
1 


if one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Bee? Sel 2 34uS 4G 
kt 

1 2 3 
é 


32k 
1 
0 0 0 
Notes: 


1. The result of the > function depends on the DCT system variable (see 
Chapter 5 for information on the OCT system variable). 

2. When the > function is used with logical data (see Chapter 2), a system 
error display can occur if the number of elements in the right argument is a 
multiple of 32. The following are examples: 


Ae he FO oll 
CSOUPAIE EE au 


To prevent this error, separate the statement into two statements as 
follows: 


First, assign the right argument for the > 
function to a variable. 


Aehke FO al 
Ye Ry Sy 
i x yf 


COUT AOE Y 


i 
& Then, use the variable as the right argument 
for the > function. 


' Primitive (Built-In) Functions 87 


1 
q 


i Page of SA21 9303-0 


| Issued 15 June 1978 
By TNL: SN21-0289° 


i 
{ 
| 
i 
| 
‘ 


j 
t 
‘ 


The < Function: Less Than or Equal To 


z i 
4 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Less Than or Equal To A<B 


The less than or equal to function result is 1 when argument A is less than or 
equal to argument B; otherwise, the result is 0. The arguments can be numeric 
scalars, vectors or other arrays. The arguments must be the same shape, 
unless one of the arguments is a scalar or any single-element array. 
Arguments of the same shape have the same shape result: 


16522 


“220 


“35-9 


“er 


ud 


If one argument is a scalar or a single-element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


Re2 Sel 2354 5 6 
B 


= 
sie oe} 
on 


pt 
= & 
a 


Notes: 
1. The result of the < function depends on the DCT system variable (see 
2. When the < function is used with logical data (see Chapter 2), a system 
error display can occur if the number of elements in the right argument is a 
multiple of 32. The following are examples: 
eye 32 el. 
Ae Ge FO pl 
CSHPAI ERE VGH 
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To prevent this error, separate the statement into two statements as 
follows: 


YeArol 


gay 


First, assign the right argument for the < 
function to a variable. 

AG ke FO pl 
Yet you 
CGUTAIEY< 


Then, use the variable as the right argument 
for the < function. 


a. 


The ~ Function: Not Equal To 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Not Equal To A+B 
The not equal to function result is 1 when argument A is not equal to argument 
B; otherwise, the result is 0. The arguments (numeric or character) can be 
scalars, vectors, or other arrays. The arguments must be the same shape, 
unless one of the arguments is a scalar or any single-element array. 
Arguments of the same shape have the same shape result: 


0x5 
j 3 
1.123#1,12% 
0 
‘ATH AS 
0 
a ee | 
1 
8.1% “1 "345.1 Fo m4 
oY1i1 


lf one argument is a scalar or a single element array, the shape of the result is 
the same as that of the other argument. The single element is applied to every 
element of the multielement array: 


‘A’ #’  ABACATIAEAFAG ' 
01020102 0721071 
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Notes: 
1. If the arguments are numeric, the result of the * function depends on the 


(ICT system variable (see Chapter 5 for information on the DCT system 
variable). _ 
The not equal to function can also be used as an exclusive or function. 
When used in this manner, the value of the arguments must be either O or 
1: 


Exclusive Or Table 


Operator-—————>- # «—— Argument A 


2. When the = function is used with logical data (see Chapter 2), a system 


error display can occur if the number of elements in the right argument is a 
mulltiple of 32. The following are examples: 


OF Ye A? pd 


Ae he FO el 
CSU TAMER Gu 


To prevent this error, separate the statement into two statements as 
follows: 


YeR? wl. 
O#y 


First, assign the right argument for the ~ 
function to a variable. 

Ae Re FO aid 
Yer éted 
CAM TAY 


Then, use the variable as the right argument 
for the # function. 


PRIMITIVE MIXED FUNCTIONS 


The mixed functions differ from scalar functions because the shape of their 
results depends on the particular mixed function rather than exclusively on the 
shape of the arguments. The following list gives a brief description of each of 
the mixed functions. Following the list, each function is discussed in detail: 


Monadic 
Mixed 
Functions 


pB 


»B 


AB 


YB 


1B 


$B or 
[i]s 
or 6B 


&B 


HB 


2B 


7B 


Name 


Shape 


Ravel 


Grade up 


Grade down 


Index 
generator 


Reverse 


Transpose 


Matrix 
inverse 


Execute 


Format 


Result 


The length of each coordinate of the 
argument. 


A vector containing the elements of 
B in the order they exist in the rows 
of B. 


The index values that would select 
the elements of B in ascending 
order. 


The index values that would select 
the elements of B. in descending 
order. 


B consecutive integers starting from 
the index origin. 


The elements of the argument 


are reversed. 


The coordinates of the argument are 
reversed. 


The inverse of a square matrix or 


the pseudoinverse of a rectangular 
matrix. 


Argument B executed as an 
expression. 


Argument B converted to a character 
array. 
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Dyadic 
Mixed 
Functions 
ApB 

A,B 

or 

A, [1]B 

A, [1]B 
A/B or 
A/[1]B or 
A/B 

A\B or 


A\[I]B or 
A\B 


AtB 


Ay 5 


A?B 


Name 


Reshape 
(structure) 


Catenate 


Laminate 


Compress 


Expand 


Take 


Drop 


Index of 


Rotate 


Generalized 


transpose 


Deal 


Result 


An array of a shape specified by 
A, using elements from B. 


The two arguments joined along an 
existing coordinate ([1] is a 
positive integer). 


The two arguments joined along a 
new coordinate ([1] is a fraction). 


The elements from B that 
correspond to the 1's in A. 


B is expanded to the format 
specified by A; 1 in A inserts an 
element from B; a O in A inserts a O 
or blank element. 


The number of elements specified 
by A are taken from B. 


The number of elements specified 
by A are dropped from B. 


The first occurrence in A of the 
elements in B. 


The elements of B are rotated as 
specified by A. If A is positive, the 
elements of B are rotated to the left. 
If A is negative, the elements of B 
are rotated to the right. 


The coordinates of B interchanged 
as specified by A. 


The number of elements specified 
by A are randomly selected from B; 
the same number is never selected 
twice. 


Dyadic 


Mixed 

Functions Name Result 

ALB Decode The value of argument B expressed 

(base value) in the number system specified by 

argument A. 
ATB Encode The representation of argument B 
(representation) in the number system specified by 

argument A. 

AeB Membership A 1 for each element of A that can 
be found in B and a O for each 
element not found. 

AEB Matrix Solution to one or more sets of 

divide linear equations with coefficient 
matrix (matrices) B and right-hand 
sides A or the least squares solution 
to one or more sets of linear 
equations. 

AB Format Argument B converted to a character 


array in the format specified by 
argument A. 


Note: The mixed functions reverse, rotate, compress, and expand, and the 
operators (see APL Operators later in this chapter) reduction and scan can be 
applied to a specific coordinate of an array. This requires the use of an index 
entry [1] that indicates the coordinate to which the mixed function or operator 
is applied. The value of the index entry can be from 1 to the number of 
coordinates in the array; the leftmost coordinate (first coordinate) has an index 
value of 1, the next coordinate has an index value of 2, and so on. A matrix, 
for example, has an index value of 1 for the row coordinate and an index value 
of 2 for the column coordinate. If an index entry is not specified, the last 
coordinate (columns) is assumed. If a - (minus) symbol is overstruck with the 
function symbol or operator symbol, the first coordinate is assumed (unless an 
index value was also used). When a function or operator is applied to a 
specific coordinate, the operation takes place between corresponding elements 
in the specified coordinate. For example, assume you have a three-rank array: 


e When the first coordinate (planes) is specified, the operation takes place 
between corresponding elements in each plane. 


e« When the second coordinate (rows) is specified, the operation takes place 
between the corresponding elements in each row per plane. 


e When the third coordinate (columns) is specified, the operation takes place 
between the corresponding elements in each column per plane. 
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The p Function: Shape, Reshape (Structure) 


Monadic (One-Argument) Form: Shape 9B 


The shape function result is the shape of the argument; it has one element for 
each coordinate of the argument, which indicates the length of that coordinate. 
The argument can be any variable or constant: 


eP' ARCTIC A Vector with Four Elements 


uh. 
ol 2 
el 235 

3 
Ae? Fol 2 4 u S 6 
ff 

Le 

mS 
pr 

Pee 


The shape function applied to a scalar yields an empty vector, because a scalar 
has no coordinates. An empty vector is indicated by a blank result line: 


Blank Result Lines 
p | t 


The instruction 9 0B yields the rank (shape of the shape, or number of 
coordinates) of B: 


Bee 2 Se CARBARFARARE ' 


i 
CAR 
BAR 
FAR 
ARE: 

als 
ee 

Po 


3 


Dyadic (Two-Argument) Form: Reshape (Structure) ApoB 


The reshape function forms an array of the shape specified by argument A 
using element(s) from argument B. The elements of argument B are placed 
into the array in row order. If there are not enough elements in argument B to 
fill the array, the elements are repeated. !f there are more elements in 
argument B than are required to fill the array, only the required number of 
elements are used. Argument A must be a nonnegative integer or vector of 
nonnegative integers. The number of elements in argument A is equal to the 
number of coordinates, or the rank, of the result. Argument B can be any 
variable or constant. If all of the elements of argument A are nonzero, then B 


cannot be an empty array: 


2 3pl 234 5 6 
ee 
uo 6 
Wu 2p ABCUEFGH ' 
AB 
cu 
EF 
GH 
Se’ MOUSETRAP ' 
MOUSE 
3 Wel23 
123 123 123 123 
123 123 123 123 
123 123 123 123 
ACH 2el 2 5 4 5 6 


A 
1 2 
a Oy 
a 
i $ 
2 4eR 
L 2 3 
ye 
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The , Function: Ravel, Catenate, Laminate (= | 
Monadic (One-Argument) Form: Ravel ,B 


The ravel function results in a vector containing the element of argument B. If 
argument B is an array, the elements in the vector are taken from argument B 

in row order. Argument B can be a scalar, vector, or other array. The resulting 
vector contains the same number of elements as argument B: 


Aeo2 2 Yel 2 3’ 2 6 FOB 


rch 
L 2 
SU 
a 
78 

! BY 


12345 67 8 
Ge? Se ABCTIEF ' 
h 

ABC 

CEE 
iB 

ABCTVEF 


Dyadic (Two-Argument) Form: Catenate or Laminate A, [I]B 


The function is catenate when the [1] entry (index entry) is an integer and 
laminate when the [!] entry is a fraction. 


Catenate (The Index [1] Entry Is an Integer) 


The catenate function joins two items along an existing coordinate. (See the 
laminate function following for a description of how to join two items along a 
new coordinate.) The index [1], if given, specifies which coordinate is 
expanded. The index entry must be a positive scalar or one-element array. If 
no index [1] is specified, the last coordinate is used. Matrices of unequal 
sizes can be joined, providing the lengths of the coordinate not specified are 
the same (see Catenation in Chapter 3): 


Ae] yp 
hey 9 8 


7 del 234 3 6 
Be? 3p7 8 9 10 11 12 


ole hee on é 
oS 6 10 li ie 


A. CLA 
: 
Y S 4 
Y & ¢ 


A, C218 
: ee ee ee: a 
oS & 10 11 12 
AsELI10 20 
1 2 3 10 
eS & 26 
10 20 30,0148 
LO 20 30 
Le ae pas 
Y S 6 
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Laminate (The Index [1] Entry Is a Fraction) 


The laminate function joins two items by creating a new coordinate specified 
by the index entry [I], which must be a positive fraction. If the index entry is 
between O and 1, the new coordinate becomes the first coordinate; if the index 
entry is between 1 and 2, the new coordinate is placed between existing 
coordinates 1 and 2 (the new coordinate that is added always has a value [or 
length] of 2). The following chart shows the positions of a new coordinate in 
the shape vector (see the following examples) when two 3 by 3 matrices are 
laminated: 


Positions of New 
Coordinate in the Shape 
Index Value Vector 


Lamination requires either that arguments A and B are the same shape or that 
one of the arguments is a scalar: 


AeS Sel 234 5 6 7 BY 
keS Sell 22 33 Wu SS 66 77 BB OY 


11 22 33 

WH SS 6S 

7? 88 99 
CeAs tl. BIB 
C 


1 2 3 
Ye & 6S 
7 8 9 
11 22 33 
WY SS 44 
77 88 99 

eC 


B84 eer oe nape Vector 


et 


$3 2 3<———_ Shape Vector 


Cea, Tl. 118 


am 
Pl. 


3 3 2-H Shape Vector 


The following examples show the result when the two matrices in the 


preceding example are catenated instead of laminated: 


ATL Ie 
A 


“eve See 


“?¢ 8G 99 
AL T2185 
1 2 43 11 22 43 
YS & Ub Sn 64 
f 8 TCR Be Vy 
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The / Function: Compress 
Monadic (One-Argument) Form 


See Reduction Operator later in this chapter under APL Operators. 


Dyadic (Two-Argument) Form: Compress A/[1]B or A/B or A#B 


The compress function selects elements from argument B corresponding in 
sequence to 1's in argument A. Argument A must be a logical scalar or vector 
having the values O or 1. Argument B can be any scalar, vector, or other array. 
Both arguments must have the same number of elements unless: 


e One of the arguments is a scalar or single-element array. 


« Argument B is a multidimensional array; then the number of elements in 
argument A must be the same as the length of the argument B coordinate 
being acted on. 


When argument B is a multidimensional array, the [1] index entry is used to 
specify the coordinate that is acted on. If the index entry is omitted, the last 
coordinate (columns) is assumed. If the A/B form is used, the first coordinate 
is assumed. The rank of the result is the same as the rank of argument B: 


Blank Display Line (empty array) 


HeS Wel 234546789 10 11 12 


i 
1 2 3 & 
oS & YY 8 
9 10 11 12 
1 0 T/CLIE The first coordinate (rows) is specified; the first 
1 2 3 & and third rows, as specified by argument A, are 
9 10 11 12 selected. 
0 2 it O/T 218 
a) The second coordinate (columns) is specified; 
& 7 the second and third columns, as specified by 
L060 Li argument A, are selected. 
1 0 I*k . 
1 2 3 4& 
9 10 11 12 
0 1 1 O78 
2 OU 
& 7 
10 44 
17K 
1 2 3 & 
oS & FF 8 
op 21. ale 
0/8 


—————_____—— Biank Display Line (empty array) 


The \ Function: Expand 


Monadic (One-Argument) Form 


See Scan Operator later in this chapter under APL Operators. 


Dyadic (Two-Argument) Form: Expand A\[I]B or A\B or AXB 


The result of the expand function is argument B expanded as indicated by 
argument A. Each 1 in argument A selects an element from argument B, and 
each O in argument A inserts a O (or blank for character data) in the result. 
Argument A must be a logical scalar or vector having the values O or 1. 
Argument B can be any scalar, vector, or other array. If argument B is a 
vector, argument A must have the same number of 1’s as the number of 
elements in argument B. If argument B is a multidimensional array, argument 
A must have the same number of 1‘s as the length of the argument B 
coordinate being acted on. 


When argument B is an array, the [1] index entry is used to specify the 
coordinate that is acted on. If the index entry is omitted, the last coordinate 
(columns) is assumed. If the AXB is used, then the first coordinate is 
assumed. 


If argument B is a scalar or single-element array, it is extended to a length 
equal to the number of 1’s in argument A. If argument B is not a scalar or 
single-element array, the rank of the result is the same as the rank of the B 
argument. 


DOE a CON oe ons 


oe, o oy e ay m : 
i a 4 P 1. z wa i wed a 


i 
eee 
Yb 8 
Lo INtiak The first coordinate (rows) is 
1 2 3 expanded; a row is inserted between 
0 0 0 the first and second row. 
yo 4 
1 i 0 INEQIB The second coordinate (columns) is 
L 20 3 expanded; a column is inserted between 
Yo 6 6 the second and third columns. 
i> O18 
Le 
00 0 
YS 4 
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The A Function: Grade Up a 


You form the A symbol by overstriking the A symbol and the | symbol. 


Monadic (One-Argument) Form: Grade Up AB 


The grade up function result is the index values that would select the elements 
of argument B in ascending order. That is, the first element of the result is 
the index of the smallest element in argument B, the next element is the 

index of the next smallest element in argument B, and so on. Argument B 
must be a numeric vector. When two or more elements in the vector have the 
same numeric value, their position in the vector determines their order in the 
result (the index value of the first occurrence appears first in the output). 

The number of elements in the result is the same as the number of elements 

in the argument: 


b3 1 3 2 4 
eth 2 ae SB 
HAeS 2D 1 Ww S 
YP 6 3 4 1 
hi 4&4 & 1S 2 
Y & 1 3 S 2 
The following example shows how the grade up function can be used to sort a 
vector into ascending order: 


Aélye 12 14 18 
A Céad 
Li a2 24 12 416 168 
The result of the grade up function is not the reverse of the grade down 
function because of the way equal elements are handled; see The Y Function: 
Grade Down for an example using the grade up and grade down functions with 


equal elements. 


Note: The result of the A function depends on the DIO system variable (see 
Chapter 5 for information on the KIO system variable). 


Dyadic (Two-Argument) Form 


There is no dyadic form. 
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The VY Function: Grade Down e& 


You form the ¥ symbol by overstriking the V symbol and the | symbol. 


Monadic (One-Argument) Form: Grade Down ¥B 


The grade down function result is the index values that would select the 
elements of the numeric vector of argument B in descending order. That is, 
the first element of the result is the index of the largest element in argument 
B, the next element is the index of the next largest element in argument B, and 
so on. Argument B must be a numeric vector. When two or more elements in 
the vector have the same numeric value, their position in the vector determines 
their order in the result (the index value of the first occurrence appears first in 
the output). The number of elements in the result is the same as the number 


of elements in the argument: 


pa 1 8 
SH 1 ue 2 

PACH 2 
135 6 2 & 

ye & 
2S 1 3 6 & 


The following example shows how the grade down function can be used to 


sort a vector in descending order: 


* 0 ae 
Aely 12 


AL PAT 
18616 15 14 


13 i1 


Primitive (Built-In) Functions 


101 


The following example shows how equal elements are handled when the grade 
up and grade down functions are used: 


Acs 2873 4 ld 1 2 3 


Ss 2 8 7 3 4&4 10 1 2 3+ Positions 2 and 9 and 5 and 10 are equal. 


Because the indices for the equal elements are in the same order (first 
occurrence first) for both the grade down and grade up functions, the grade 
down function is not the reverse of the grade up function: 


AUTAT 
10 87 S43 S221 
AL AAT 
1223 345 7 8 10 
Note: The result of the VY function depends on the DIO system variable (see 
Chapter 5 for information on the DIO system variable). 


Dyadic (Two-Argument) Form 


There is no dyadic form. 
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The ¢ Function: Take 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Take A+B 


The take function result is the number of elements specified by argument A, 
taken from argument B. Argument B can be a scalar, vector, or other array. 
Argument A must be a scalar or vector of integers. If argument B is a vector, 
argument A must be a scalar. Argument A must be a vector with an element 
for each coordinate of argument B. When argument A is positive, the first 
elements of argument B are taken; when argument A is negative, the last 
elements are taken. If argument A specifies more elements than the number of 
elements in argument B, the result is padded with O’s (or blanks for character 
data). The shape of the result is the value of A: 


“Stl 2 


7tl 23 4 S 
1234 5 0 0 
~?éf1 235 4 3 
00 2 234 S 
Bes Yel 284% 5 678 Y 10 11 12 
fr 
1 2 8 4& 
3+ 6© ¢ §& 
9° io 11 $12 


2 ST 
eae 
3 & 7 


Be? 2 Jel 24384 3 6 7 8 FY 10 11 12 


Rk. 
1 2 3 
YS 4 
4 2 Y 
10 21 12 

toi site 
1 

2“ Ll ith 
1 
“7 

1 2 STB 
Lo2 3 
WS } 

“1 2 3T& 
* 8 F 
10 11 12 
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The ¥ Function: Drop 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Drop A+B 


The drop function result is the remaining elements of arguments B after the 
number of elements specified by argument A is dropped. Argument B can be 
a vector or other array. Argument A must be a scalar if argument B is a 
vector. 


When argument B is an array, argument A must have one element for each 
coordinate of argument B. When argument A is positive, the first elements of 
argument B are dropped from the result; when argument A is negative, the last 
elements are dropped: 


S41 2 3 


Bes Yoel 234 5 6 7 & Y 10 Td ie 


kt 
1 2 3 4H 
oS & YF 8 
9 10 Li 12 
1 248 
i 
11 12 
“1 “248 
L 2 
A 


The 1 Function: Index Generator, Index of 


Monadic (One-Argument) Form: Index Generator 1B 


The index generator function result is a vector containing the first B integers, 
starting with the index origin (see DIO system variable in Chapter 5). The 
argument can be a nonnegative integer that is either a scalar or a 
single-~element array: 


ae) 
12 3 4 8 
At TS 
s) 
123 4 35 4 
tit \ Si—-——— Each of the generated integers is added to 5. 


678 9 10 


Dyadic (Two-Argument) Form: Index of A1B 


The index of function result is the index of the first occurrence in argument A 
of the element(s) in argument B. Argument A must be a vector. Argument B 
can be a scalar, vector, or array. The result is the same shape as argument B. 
If the element in argument B cannot be found in argument A, the value of the 
index for that element is one greater than the largest index of A (UIO+pA): 


” ne = ne c° i 
z tad wl vd 3 1 ud 
CO al 


ARBCTER GS yt 


Second Element 
3 
AéelLi 22 44 Wy Be 


c 
&. 
é 

Sp. 
an 


Ac? 2e 8B 24 b 
Bee: ed OF ak ae 
B 


Note: The result of the 1 function depends on the DIO system variable (see 
Chapter 5 for information on the LIIO system variable). 


The Function: Reverse, Rotate @ 


You form the $ symbol by overstriking the © symbol and the | symbol. A 
special form of the function symbol is ©, which you form by overstriking the O 
symbol and the - symbol. 


Monadic (One-Argument) Form: Reverse [1]B or $B or ©B 


The reverse function reverses the elements of argument B. Argument B can be 
any expression. 


Primitive (Built-In) Functions 105 


When argument B is a multidimensional array, the index entry [1] can be used 
to specify the coordinate that is acted on. If the index entry is omitted, the 
last coordinate (columns) is acted on. If the ©B form is used, then the first 
coordinate is acted on: 


bi 2 34 | 
YS 21 
bo LIVE' 


pe Be. 
ecm | 
& & yy 
Ae? 2 ie ‘SAVEMUCHMORETIME' 
fy 
SAVE 


MUCH 


MORE 
TIME 
Pc Laa 
MORE The first coordinate (plane) is specified; 
TIME the planes are reversed. 


SAVE 
MUCH 
Drea 
MUCH The second coordinate (rows) is specified; 
AWE the rows in each plane are reversed. 


TIME 
MORE 
0 ea 
EVAS The third coordinate (columns) is 
HOLM specified; the columns in each plane are 
reversed. 


hey 


EVA 3 The last coordinate is acted on. 
HOLM 


ROM 
EMIT 
fy 
MORE The first coordinate is acted on. 
TIME 
SAVE 
MUCH 
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Dyadic (Two-Argument) Form: Rotate A%[1]B or ADB or AGB 


The rotate function rotates the elements of argument B the number of 
positions specified by argument A. If argument A is positive, then the 
elements of argument B are rotated to the left (rows), or upward (columns). If 
A is negative, the elements are rotated to the right (rows), or downward 
(columns). Argument B can be any expression. The shape of the result is the 
same as that of argument B. 


When argument B is a multidimensional array, the index entry [|] can be used 
to specify the coordinate that is acted on. If the index entry is omitted, the 
last coordinate (column) is acted on. If the A@B form is used, then the first 
coordinate is acted on. 


If argument B is a vector, then argument A must be a scalar or single-element 
array. If argument B is a matrix, then argument A must be a scalar or vector. 
When argument A is a vector, the number of elements in argument A must be 
the same as the number of elements in the coordinate being rotated. For 
example, if B is a 3 by 4 matrix (each row has four elements) and the row 
coordinate is specified, A must have four elements: 


edi 2 
34 3 1 2 

“201 2 3 4 S 
YS 12 3 


a ee ee ae 


34 3S 1 2 
Bes be ft 2 34 & 6& 7 BF 10 11 te 
Z i 7 The first coordinate (rows) is specified; 
| 2 a therefore, the rotation is between rows. 
ou & %¢ 8 
9 10 11 12 5 2 7 12 
1 0 1 200108 
uo af 7 Te 9 6 11] 4 
9 46 ITI & 
ii0 3 8 J Ar J 
Q 1 200208 
1 2 3 
& 2 8 The second coordinate (columns) is specified; 
14 42 9 10 therefore, the rotation is between columns. 
0 1 208 
1 2 S$ uN : £ 
” £3 c The tast coordinate is acted on. 
11 12 9 10 
Aé-1 0 1 2 
ra) 
“1 0 “2 “2 
ADT A AE 
> 2 11 8 
1 & 8 Le 
2 10 ¢ 
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If argument B is an N-rank array, argument A must be a scalar or an array 
with a rank that is one less than the rank of argument B. The shape of 
argument A must be the same as argument B less the coordinate being acted 
on: 


Bes 3 3pi27? 
i 


3 3 3 
A¢3S Sel 0002720 0 0 0 
A 
1006 The shape of argument A must be the same 
0 2 eee as argument B less the coordinate being 
0 0 acted on. 
Pr 
3 3 
AGC LAG . 
1 : me : The first coordinate (planes) is specified; 


therefore, the rotation is between planes. 
The first element Argument A 
in each plane is 
‘ ae rotated one position 
16 17 18 ‘ . 
between planes. 


120 24 The middle 
"° 14 arn element in each 
_ 9 f, 7 plane is rotated two 
Bo OS te game Be positions between 

“ 

4 eae planes. 

% 8 6 

1 8 9Y 

The second coordinate (rows) is specified: 

10 Wl? 2 therefore, the rotation is between the rows. 
fe a Fe et 


16 14 18 fo Argument A 


Rotation between rows of 
the first plane 

Rotation between rows of 
the second plane 


Rotation between rows of 
the third plane 
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The & Function: Transpose, Generalized Transpose 


You form the & symbol by overstriking the © symbol and the \ symbol. 


Monadic (One-Argument) Form: Transpose &B 


The transpose function reverses the coordinates of argument B. Argument B 
can be any expression. If argument B is a scalar or vector, the argument is 
unchanged by the function: 


7 


ABCT 


Qn? 
8 ABCTU 


Be2 34 3 6 


k 


Sel 2 


3 2-row 3-column matrix. 


& 
RE 


= ——_ 3-row 2-column matrix. 
Ss 


3 aye 


ty. 


8 

12 

16 

20 

at 
14. 
18 
ard 

Ma The coordinates are reversed. 
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Dyadic (Two-Argument) Form: Generalized Transpose A&B 


The generalized transpose function interchanges the coordinates of argument B 
as specified by argument A. Argument B can be any expression. Argument A 
must be a vector or a scalar, and must have an element for each coordinate of 
argument B; also, argument A must contain all the integers between O or 1 
(depending on the index origin) and the largest integer specified. For example, 
to transpose the rows and columns of a matrix, argument A would be 2 1: 


Be2 Sel 23 4 8 6 


12 °3 
ye 


1 4 
2S 


3 6 


To transpose the rows and columns of a three-rank (three-coordinate) array, 
argument A would be 1 3 2: 


Ree 3 bere 


us 
: re a Oe. 
~~ & FF 8B 
9 10 41 12 


An array with two planes, three rows, and four columns. 


lL S 
~ & 10 
3 7? di 
Y 8 12 The second and third coordinates have been interchanged, 
. Dae forming an array with two planes, four rows, and three 
1 Sol? od columns. 


15 19 2¢ 


L6é 20 24 


The ? Function: Deal al 
Monadic (One-Argument) Form 


See the roll function earlier in this chapter under Primitive Scalar Functions. 


Dyadic (Two-Argument) Form: Deal A?B 


The deal function randomly selects numbers from O through B-1 or 1 through 
B (depending on the index origin), without selecting the same number twice. 
Both arguments must be single positive integers. Argument A must be less 
than or equal to argument B; argument A determines how many numbers are 


selected: 
1°77 
ly. 
2? 
¢ 3 
rrr) 
Set? 38 6 U 
Fee 
S$ 2 417 6 4 
727 
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The 1 Function: Decode (Base Value) 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Decode ALB 
The decode function result is the value of argument B expressed in the number 
system specified by argument A. For example, to convert the vector 1 7 7 6 to 


its value in the decimal number system (base 10): 


10 10 120 10,1 7 7 4 
17764 


The following illustration shows how it was done: 
Argument A (number system) specifies the following: 
10 10 10 10 


Ten units in each of these positions equal one unit 
of the next position to the left. 


Argument B is a vector with these values: 


1776 


The result is the same as doing the following: 


The units position always represents itself. 


The value in the next position is multiplied 
0x10x10 = 1000 by the rightmost value in argument A. 
1776 
The value in the next position is multiplied 
by the two rightmost values in argument A, 
and so on. 


The arguments must be numeric. If one argument is a scalar or single-element 
array, the other argument can be a scalar, vector, or other array. The result will 
have the rank of the larger argument minus one. 


If either argument A or B is not a scalar, they both must have the same length, 
or an error results. 


Note: The value of the leftmost position of argument A can be zero, because 
even though there must be a value in that position, it is not used when the 
result is calculated. For example: 


Oe Ee a ea oe a 1G 
LU re 


If either argument is a scalar, the value of that argument is repeated to match 
the length of the other: 


5 1=1 
1x2=2 
1x2x2=4 


ee, 


lf argument A is a vector and argument B is a matrix, argument A must have 
an element for each row of B: 


If argument A is a matrix and argument B is a vector, each row of argument A 
is a Separate conversion factor; argument B must be the same length as a row 
of argument A. The result will be a vector with one element for each row of 
argument A: 


ee SeLU 10 10155 22 


10 Lo a "4 04 This number system could 
1 16 represent yards, feet, and inches. 
Ahi 2 1x3 x12=36 
eee Be 63 
Aawe 3 bt 
2s Lis 
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If both arguments are matrices, each row of A (conversion factor) is applied to 
each column of B. The result is a matrix containing the converted values for 
each column of B: 


Ate? 42e8 8 B 146 14 164 
Hes Bel 2 2 12 3 3 
r 
G3 8 & 
14 16 14 
kk 
> 412 lay 
2. eee 2 x8 = 16 ae. 4 
owt 4x8 x8 = 64 > 
ak a 83 12 x 16 = 192 
ae : 
ie ae 2x16 x16= 512 
291 $7074 —.——————_ ~~. — 7077 


The following examples convert hours, minutes, and seconds to all seconds: 


m4 460 4041 30 15 


a os 
The following illustration shows how it was done: 
Argument A (number system) 
24 60 60 
He 60) units (seconds) equal one unit of 


the next position to the left. 


60 units (minutes) equal one unit of the 
next position to the left. 


24 units (hours) equal one unit of the 
next position. 


Argument B 
1 (hour) 30 (minutes) 15 (seconds) 


The result was obtained as follows: 


15 = 15 seconds 
30x60 = 1800 seconds 
1x60x60 = 3600 seconds 


5415 seconds 


The T Function: Encode (Representation) 
N 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Encode ATB 


This function is the reverse of the decode function. The encode function result 
is the representation of argument B in the number system specified by 
argument A. 


Note: Be sure argument A is long enough to completely represent argument B 
or an incorrect answer results. 


For example, the representation of 1776 in the decimal number system (base 
10): 


10 10 10 LO0r1?74 
1 7 7 4 


The following illustration shows how it was done: 


Argument A (number system) specifies the following: 


10 10 10 10 
i Ae et es Ten units in each of these positions equal 


one unit of the next position to the left. 
Argument B has this value: 


1776 
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" The result is the same as doing the following: 


1000 
776 


70 
Note: The value of the leftmost position of argument A can be zero. For 
example: 
0 10 10 Tori 7rsé 
1? 7 4 


If both arguments are vectors, the result is a matrix. Each column in the result 
contains the representation for each element of argument B expressed in the 
number system specified by argument A: 


116 


If argument A is a matrix and argument B is a scalar, then the result is a 


matrix. Each column of the result contains the values of argument B expressed 
in the number system specified by the corresponding column of argument A: 


Aes Bee 14 


8 x8=64 [123 
64 


8 
f} 
7 
Lt 
RATE ~—_—_-—— The result can be transposed so that 
1 * 3 each row represents the values of 
0 Y di 


argument B expressed in the number 
systems specified by argument A. 


If argument A is a scalar or vector and argument B is a matrix, the result is a 
matrix or N-rank array, with one plane for each element of argument A: 


Atl 3 12 
Re? 2e4h 24 46 Le 
A 
se mage 


~+—_———— This number system could 
E represent yards, feet, and inches. 


3 x12= 36 aan | 


2 Feet 11 Inches 
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if both arguments are matrices, the result is an N-rank array, with one plane 
for each element of argument A. Each column of argument A represents a 


number system: 


Ae? 2010 20 


2p 99 B88 7? 66 


Result of the number system in 
column 1 of argument A 


Result of the number system in 
column 2 of argument A 


The following example converts seconds to seconds, minutes, and hours: 


ou 40 40 7 Suds 


1 30 15 
The following illustration shows how it was done: 
Argument A (number system) 


24 60 60 


—_— 


60 units (seconds) equal one unit of the next 
position to the left. 


60 units (minutes) equal one unit of the next 
position to the left. 


24 units (hours) equal one unit of the next 
position to the left. 


Argument B 
5415 (seconds) 


The result was obtained as follows: 
a 
60 x 60 = 3600 [5415 


3600 
1815 


60 [1815 
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The € Function: Membership 


Monadic (One-Argument) Form 


There is no monadic form. 


Dyadic (Two-Argument) Form: Membership AeB 


The membership function result is a 1 for each element of argument A that can 
be found among the elements of argument B and a O for every element that 
cannot be found. The shape of the result is the same as the shape of 
argument A. Arguments A and B can be any scalar, vector, or array: 


x3 


Wel 2 3 4 OS 
1.$e] 2 3 4 S 
‘Aa  RANNA' 
‘A' ae ' BANANA’ 
"ARC ¢ BANANA’ 


Ate gel 3 2 7 
Bel. ele Wo 78 


g 
wo 78 Le 
78 12 Ws 
12 We 78 
we FB 12 
Ae 


Bel Wel 24 ae 
A 


¥ 

a 
per 
i § 
ye 
hel 


The & Function: Matrix Inverse, Matrix Divide 


You form the & symbol by overstriking the 0 and the + symbols. 
Monadic (One-Argument) Form: Matrix Inverse HIB 


The matrix inverse function inverts a nonsingular matrix or computes the 
pseudoinverse of a rectangular matrix. The result is a matrix. Argument B 
must be a numeric matrix, and the number of columns must not exceed the 
number of rows. The number of columns in the argument is the number of 
rows in the result, and vice versa. 


If argument B is a nonsingular matrix, HB is the inverse of B. If the matrix 
does not have an inverse, then DOMAIN ERROR results: 


Ae? Poel 3 8 7 
my 
pee 
oe 
Rey 
“ODO, 873 0.3875 
1.425) ei ree es 
Ae? Bel 2 3 4 
4 
L 2 
4 
BA 
QOMAIN ERROR 
BA 


a 


If argument B is a rectangular matrix, HB is the pseudoinverse of the matrix 
(least squares solution): 


ACS 2ep3 5S 1 2 2 Ut 

A 
Xe 
1 2 
2M 

Fle 

es me a 
0.4 1.2 


Dyadic (Two-Argument) Form: Matrix Divide AB 


The matrix divide function solves one or more sets of linear equations with 
coefficient matrices. Argument B must be a numeric matrix. The number of 
columns in B must not exceed the number of rows. Argument A must be a 
numeric vector or a matrix. The length of the first coordinate of argument A 
must equal the length of the first coordinate of argument B. 
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The rank of the result is the same as the rank of argument B. The length of 
the first coordinate of the result is the same as the number of columns in 
argument B. If argument A is a matrix, then the second coordinate of the 
result is the same length as the second coordinate of argument A. 


If argument B is a square matrix and argument A is a vector, then the result is 
the solution to the set of linear equations with coefficient matrix B and 
right-hand sides A: 


Ae 3 
Bee. ek iad od 
ALAR 

2 3 
Heo gpa s0- a: a 
B 

ae, 

1 2 
2& DEE 

a 


If argument B is a square matrix and argument A is a matrix, then the columns 
of the result are the solution to the sets of linear equations with coefficient 
matrix B and right~hand sides equal to the columns of A: 


Ae2 2p24 16 9 4 
Re? 2e3 S12 


Pi 
2h 164 
Y 4 
hh 
3S 
: oo 
AE 
Ms ; 


| oy 
al. fee 


If argument B is rectangular, then the result is the least squares solution to one 
or more sets of linear equations: 


a a 
booF TY 
is a 
25 
12 
OAL 
AEIE 
ar ? | 
“ud ? | 


The 2 Function: Execute 


You form the © symbol by overstriking the 1 and the © symbols. 


Monadic (One-Argument) Form: Execute 2B 


The execute function evaluates and executes argument B as an APL expression. 
Argument B can be any character scalar or vector: 


A&' T+t2° 
ra) 
Lee 
£ & —————_—— The character vector in the variable A is executed. 


3 


De ' CCAM) + Obes) de 
hye 3 
Be 
20 
Ka 
At 4 
Be 
aC 
10 


fe 
Be? 


aCA=B)/' At! 
ee > A +B is executed only when A equals B. 
RCAa B/S AE 


Dyadic (Two-Argument) Form 


There is no dyadic form. 
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The ? Function: Format . 


You form the ? symbol by overstriking the T and the ° symbols. 


Monadic (One-Argument) Form: Format *B 


The monadic format function result is a character array that is identical in 
appearance to the one displayed when the value of argument B is requested: 


Re3 Warde 


i 
1 2 3 4& 
oS & FF 8 
9 10 11 12 

Xe ¥h 

x 


2 8 4 . 
& ~ & ~j——— This matrix is a character matrix. 
LQ 11 12 


“O de 


Dyadic (Two-Argument) Form: Format A®B- 


The dyadic format function result, like the monadic format function result, is a 
character array. However, argument A is used to control the format (the 
spacing and precision) of the result. Argument A is a pair of numbers: the first 
number determines the total width of the format for each element, and the 
second number determines the precision used. 


124 


lf the precision number is positive, the result is in the decimal form, with the 
number of decimal places specified by the precision number. If the precision 
number is negative, the result is in scaled form, with the number of digits to 
the left of the E specified by the precision number: 


Bes 2e12, 34 “34.967 0 12 "0.26 "123,45 


b 
12, 34. “Sy SS? 
i) 12 
“0,26 “1235 45 
X¢9 2th 
x 
Le. 34 “RYO? 
00 12,06 


“26; “L235 


(left margin) 


(e9 “Sek 


1.3604 "3.504 
O.0E "O01 4.3604 
“9 6E OU) 71. 2602 


me Width of Nine Positions 


(left margin) 


If the width entry in argument A is zero, the 5110 uses a field width such that 
at least one space will be left between adjacent numbers. If only a single 
number is used, a width entry of zero is assumed: 


Ee 29 
: 
12.34 “S4,57 
.00 12,00 
| ~.2d) “123.45 


te ae 


PO ee ee Width of Eight Positions 


(left margin) 


If you get a DOMAIN ERROR when using the format function, increase the 
width (left digit) of the left argument. 
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You can format each column of an array differently by using a control pair in 
argument A for each column of the array: 


Fede 2 4 Lek 
|e 
12,34 “SUG 
O00 12.0 
“ed 12s. 


we eee ee ee’ 


pL of Six Positions 


(left margin) 


Notes: 

1. If the DPW system variable is set to an invalid value, OPW IMPLICIT 
ERROR will result when the format function is used. 

2. Even if the specified format causes all of the significant digits to be 
truncated, the sign of the original number is retained, For example: 


h 27, 0004 
4 00 it : 
The sign is retained. 


3. The format function should not be used to round a number up or down. 
Instead, the floor function should be used for rounding. For example, L A+.5 
rounds the value of A to the nearest integer. 
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APL OPERATORS 


An APL operator applies one or more dyadic primitive scalar functions to 
arrays. The operators are reduction, inner product, outer product, and scan. 


Reduction Operator (/) 


The symbol for the reduction operator is /. The forms of reduction are (f)/[1]B 
or @)/B or (f)4B, where (f)can be any primitive dyadic scalar function that is 
applied between the elements of a single vector. 


The rank of the result is one less than the rank of argument B, unless 

argument B is a scalar or a single-element vector; then the result is the value 
of the single element of argument B. When argument B is a vector, the 
reduction of that vector is the same as putting the primitive dyadic function 
between the elements: 


Bed 2 3 4 
of. / a 
10 
Lee eel 
10 ° 


If argument B is an empty vector (see Chapter 3), then the result is the identity 
element, if one exists, for the specified function. For example: 


x/y0 
i-——_—————— The identity element of x (times) is 1. 


When argument B is a multidimensional array, the [1] index entry is used to 
specify the coordinate acted on. If the index entry is omitted, the last 
coordinate (columns) is acted on. If the(f)/B form is used, the first coordinate 
is acted on. Indexing along a nonexistent coordinate will result in INDEX 
ERROR. 
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When argument B is a multidimensional array, the coordinate of argument B 
that is acted on is eliminated: 


i 


Re? Sol 2 3 4 5 4 


i 
p eae 
- 4 4 
+f IS 
& 1% SN ————— Thee last coordinate (columns) is assumed; 
4/E2 16 therefore, the reduction is between columns: 
& 1S 
+f 1+2+3=6 
a ee alee 
i We The second coordinate (in this case, columns) 
oa a is specified. 
Be? S Wore 
fi The first coordinate (rows) is specified; 
a therefore, the reduction is between rows: 
& FF 8 
10 at 12 1 2 3 
4 5 6 
14 15 16 5 7 9 
1? 18 19 20 
21 22 23 24 
+ / 10118 
14 18 oq "The first coordinate 
> Ou 246 28 (planes) is specified; 
Bo Ry ZS therefore, the reduction 
he 4 Q is between planes. 
Ik 
+/ FB 
0 
a / Ti 
1 
P/E 


“FT 2S PETS 


If argument B is an array that has a coordinate whose dimension is zero, then 
reduction along that coordinate yields an array whose elements are equal to 
the right identity element for the function, if the right identity element exists. 
The identity element for each function is given in the preceding table. 
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Inner Product Operator (.) (] 


The symbol for the inner product operator is . (period). The inner product 
operator is used to combine any two primitive scalar dyadic functions and 
cause them to operate on an array. An example of its use would be in matrix 


=". algebra, in finding the matrix préduct of two matrices. The form for inner 


product is: A). @ B, where @)and © are any ‘primitive scalar dyadic 
functions. Function (Q) is performed first and then () reduction is applied 
between the results of function @). - 


The result is an array; the shape of the array is all but the last coordinate of 
argument A catenated to all but the first coordinate of argument B 
(_1+pA),(1498B). If argument A and argument B are matrices, the elements in 
each row of argument A are acted on by the elements in each column of 
argument B: 


AtC2 Pel 2 3 4 
Re? Pos 6 7 8 
A 


i 


8 (158) + (2x7) = 19 
a A+ XB 
: ey 


The above example is the same as doing the following for each element in the 


result: 
C1x5)+02x%7) 

19 
(1%6)4+02%8) 

Le 
CSxS+ CU 7) 

3 
CAXGD + CUXG) 

oO 
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“1 —- 
| 


The shapes of arguments A and B must conform to one of the following 
conditions: 


1. Either A or B is a scalar. 


oy , ae : At2 2p i ‘2 3. y OTS RD ay TT niet rer eee ogre oS UE et cet 
Bes 
A 
B 


2. The last coordinate of argument A is the same length as the first 
coordinate of argument B. (If both are matrices, the column coordinate 
of argument A is the same length as the row coordinate of argument B.) 


AtS Pei 23435 64 
BRe2 Se? 8% 10 11 12 


9 
& 12 
At+,xE 7 
oy 30/7 3a0 ae 
61 68 75 


93 106 117 


At TIAN’ 


Rey Se ‘TONDTANMEL TOM ' 

A 
TIAN 

B Transpose B so that the first coordinate of 
NON B has the same length as the last coordinate 
DAN of A. 
MEL, 
TOM 

AA, = 
0 1 0 0 


The second row of B is equal to A. 


Notice that the inner product operator can be used to find equal names in a 
matrix (table). However, if you use the inner product operator with the v and ~ 
functions, unpredictable results can occur. instead, you should use a statement 
like ~AA.=B. For example: 


AA, =aR 


If argument A and argument B are N-rank arrays, the elements in each row of 
argument A are acted on by the elements in each plane of argument B: 


A€e 2 2eig 


Ree 2 2eG++ 1B 
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Outer Product Operator (° .) & 


The symbols for the outer product operator are © .. The outer product 
operator causes a specified primitive scalar dyadic function to be applied 
between argument A and argument B so that every element of argument A is 
evaluated against every element of argument B. The form of the function is: 
Ae, @®B, where (f)is a dyadic primitive scalar function. Arguments A and B 
can be any expressions. Unless argument A is a scalar, the shape of the result 
is the shape of argument A catenated to the shape of argument B. If argument 
A is a scalar, the shape of the result is the same as the shape of argument B: 


Ae e 
Rel 2 3 4 
A 


As ,x& 
zu & 8 
Atl 2 3 
Bes WS 
a 


i 


sd 


Ae, xB 
uo 
@ 10 


12 15 


The above example is the same as doing the following for each element in the 


result: FE: 

1x3 
3 

wa 
ly. 

xs 

mK 4 
& 

2X Uy. 
3 

ee ae) 
10 

aX 
9 

AKU 
Lat 

xe 
i ee 
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More examples: 


At 2 
Be? Fol 2 Su & 6 
Ae, + 


a 


wp. F 

Pe ed 
_— 

os 


A&e! Bel 2 & 
Kes Se.9 
ray 


ad 
& YY & 
7 10 14 
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Scan Operator (\) 


The symbol for the scan operator is \. The forms of scan are: 

@ \[1]B, @ \B or@)B, where(f)can be any scalar dyadic primitive function 
and argument B is a numeric vector or other array. The scan operator, like the 
reduction operator, operates on the elements of a single vector, and is the 
same as putting the primitive dyadic function between the elements. But the 
scan operator accumulates the results as the operation is repeated along the 
vector. The shape of the result is the same as that of the input argument: 


#t\) 2 3 4 3 
13 6 10 15————— This result is the same as doing the 
‘L following for each element in the 
a result. The first element in the 


Lb? result is the first element of the 
a argument. 
Lt24+3 
& 
Lt 2 Se 
10 
Lt Stl eS 
LS 


When argument B is a multidimensional array, the [|] index entry is used to 
specify the coordinate the scan is to proceed along. If the index entry is 
omitted, the last coordinate (columns) is acted on. If the(f) \B form is used, 
the first coordinate is acted on. 


Bes Ward? 


is 
1 2 3 4& 
oo & jf 8 
9 10 411 °#12 
+\U0 18 «—————- The first coordinate (rows) is specified; therefore, 
2 3S & the scan is between rows. 
8 10 12 
18 21 24 


Ly: 


<«—______—_—_ The second coordinate (columns) is specified; 
therefore, the scan is between columns. 


I 
2d 24. 


kame 
- 
~ 
EBS 


Ae2 3 Wer2y 
A | 
1 2 8 4 
5 4 7 8 
910 11 12 


#\ E1746 «The first coordinate (planes) is specified; 
1 2 3% u therefore, the scan operation is between planes. 
5 & %F 8 


30 Be Su 36 

\E 2 1A <-——————- The second coordinate (rows) is specified; 
1 2 x y. therefore, the scan operation is between rows 
6 8 10 12 for each plane. 

18 $168 21 24 


* 
ol 


13 14 1S 16 
30 32 34 34 
31 S34 3S? 60 
#\ 34 «——————- The third coordinate (columns) is specified; 


1 3 6 10 therefore, the scan operation is between columns 
% 21 18 26 for each plane. 


17 30 4A 
13 27 4A 38 
1? 3S Su 7 
21 43 66 20 
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SPECIAL SYMBOLS 


Assignment Arrow + 


The assignment arrow causes APL to evaluate everything to the right of the 
arrow and associate that value with the name to the left of the arrow. For 
example, A«2+3 means that 2+3, or 5, is assigned to the name A. When A is 
used in a later APL statement, it has a value of 5. 


Notes: 


1. When a value assigned to a variable is used as the argument for a function, 
the value assigned to the variable is used by the function, regardless of any 
previous or future value assigned to the variable. For example: 


At Y 
CAGES) +A 
& 
A 
3 
CAG SI +064 
¢ 
A 
3 


2. To avoid confusion, a variable should not be referenced in the same 
expression it is assigned, except directly to the right of the assignment. For 


example: 
feo? 
Ae Ad 
A 
3 


Branch Arrow > 


The branch arrow is used for the following: 


* To change the order in which the statements are executed in a user-defined 
function. See Branching in Chapter 6 for more information on branching. 


« To resume execution of a suspended function. 


* To clear the state indicator. 


Quad 0 


The quad is used to ask for input and to display output. To display output, the - 
quad must appear immediately to the left of the assignment arrow. The value 
of the APL expression to the right of the arrow is assigned to the quad and 

will be displayed. For example: 


wt fle b+ 3 
Z 
La 

AeéTe CHARACTER DATA’ 
CHARACTER DATA 


The 7 displayed is the value assigned to the quad. The 12 is the final 
evaluation of the APL expression. 


When used to ask for input, the quad can appear anywhere except to the 
immediate left of the assignment arrow. Execution of the expression stops at 
the quad and resumes when an expression is entered to replace the quad. 
When a quad is encountered, the quad and colon symbols (1) :) are displayed 
to indicate that input is requested. For example: 


1090 


See Chapter 6 for more information on quad input or output within a 
user-defined function. 


Quad Quote 1 () 
L K 


You form the quad quote symbol by overstriking the quote symbol ' and the 
quad symbol (]. The quad quote operates the same way as the quad when 
requesting input, except that the data entered is treated as character data. For 
example: 


Kell 
CAN T 

X 
CANS T 

oo 
"CAN TT! 

x 
"CAN'T TT! 


Note: If a system command is entered for a quad quote input request, the 
system command is treated as a character string and will not be executed. 


See Chapter 6 for more information on quad quote input or output within a 
user-defined function. 
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The comment symbol is formed by overstriking the N symbol and the ° 
symbol. The comment symbol must be the first nonblank character in d line 
and indicates that the line should not be executed. For example: 


VONE PLUS Two 
Dil aTHe PURPOSE OF THIS FUNCTION 
P20. aTQO Ant TWO NUMBERS TOGETHER! 
PS] ONE + TWOY 
12 PLUS 3h. 


TS 


Le & 


Parentheses (_ ) 


Parentheses are used to specify the order of execution. The order of execution 


is from right to left with the expressions in parentheses resolved (right to left) 
as they are encountered. For example: 


Bale x & 


ys 
No 


CaM DRG 
We 


SYSTEM VARIABLES 


Chapter 5. System Variables and System Functions 


System variables provide controls for the system and information about the 
system to the user. These variables can be used by a function as arguments 
the same as any variable. 


The following is a list of the system variables and their meanings. A complete 
description of each follows the list: 


Variable Name 


Oct 
Do 
OPP 
OPw 
ORL 
Oc 
OWA 
OLX 
DAV 


Notes: 


Meaning 


Comparison tolerance 
Index origin 

Printing precision 
Printing width 
Random link 

Line counter 
Workspace available 
Latent expression 
Atomic vector 


1. To find the value assigned to a system variable, enter the variable name. 
The value assigned to the OCT, O10, Opp, Opw, ORL, and OLX system 
variables can be changed by the assignment arrow (+). For example, 
entering D10<0 assigns the value O to the [IO system variable. 

2. The use of any system variable causes an entry to be made in the symbol 
table for that symbol. Therefore, if the symbol table is full, a SYMBOL 
TABLE FULL error is generated. ) 

3. The following system variables are implemented as part of the system for 
the purpose of maintaining syntactic compatibility between the 5110 and 


APL/SV or VS/APL: 


Variable Name 


DAI 

ODL 
OTs 
OTT 
OUL 


Meaning 


Accounting information 
Delay 

Time stamp 

Terminal type 

User load 


Default Value 


0000 

0) 

1900 000000 
0) 


1 


Although these system variables are not generally used with the 5110, the 
QAI and OTS system variables can be assigned a new value. 
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Comparison Tolerance: OCT 


The value of this variable determines the maximum tolerance (how different the 
two numbers must be to be considered unequal) when any relational function 
is used and at least one argument is a noninteger. For example, two numbers 
are considered unequal if the relative difference between the two numbers 
exceeds the comparison tolerance value. The following illustration shows how 
the comparison tolerance works with the relational functions: 


4[]CTxA’ 
(te Value of argument A 


Real number line 


The relationship of 
any value (argument B) 
to argument A 


—=-—— A>B 
———— A>B 


A’ is the next lower integer power of 16 for the largest argument. For 
example: 


. L4%0 ] 2 % +—~The First Five Integer Powers of 16. 
1 16 256 4096 6853564 
Mores dt 
eds, Next lower integer power (A’) is 1; 
0 therefore, the difference between the 
arguments exceeds +(]CTxA’ (.1x1=.1) 


BL, Next lower integer power (A’) is 16; 
1 therefore, the difference between the 
arguments does not exceed +IJCTxA’ 
(.1x 16=1.6). 


Ai Loe be ie Next lower integer power (A’) is 16; 
0} therefore, the difference between the 
arguments exceeds +[)CTXA' 
(.1X16=1.6). 
ee Next lower integer power (A’) is 256; 
1. therefore, the difference between the 
arguments does not exceed +L]CTxA’ 
(.1 x 256=25.6). 


Note: The DICT function considers any number in decimal form a noninteger. 
For example, 1000 is an integer and 1000. is a noninteger. 
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The value of the comparison tolerance variable also affects the floor and ceiling 
functions. The comparison tolerance is added to the argument for the floor 
function and subtracted for the ceiling function. For example: 


Te . O38 

L2. 98 2.98 + .03 = 3.01 (The integer 3 is in the range of 
3 2.98 + .03.) 

[2 PS 2.96 + .03 = 2.99 

Peas 3.03 - .03 = 3 (The integer 3 is in the range of 
3 3.03 - .03.) 

Pia. Gu 3.04 - .03 = 3.01 


in a clear workspace, the comparison tolerance value is set to 1E 13 (see 
Chapter 3 for an explanation of scaled representation). 


Index Origin: O10 


The value of this variable determines the index origin. The value can be either 
O or 1, which means that the first component of a vector or array is indexed 
with a O or 1, depending on what the value is set to. In a clear workspace, the 
value is set to 1. 


The functions affected by index origin are indexing ([ ]), index generator (1), 
index of (1), roll (?), deal (?), generalized transpose (&), grade up (A), and 
grade down (¥). 


PiOe The index values represented by the 
12 3 bail 2 3 & result start from O rather than 1. 
6 12.3 
he 3 WS 
23 2 
ag 


toed 


Note: All other examples in this manual are shown with the index origin set to 
‘Ly 


System Variables and System Functions 


141 


Printing Precision: OPP 


The value of this variable determines the number of significant digits displayed 
for decimal numbers and for integers with more than 10 digits. The value of 
this variable does not affect the internal precison of the system. The value can 
be from 1 to 16. In a clear workspace, the value is set to 5. This means that 
the number of significant digits displayed for decimal numbers or for integers 
with more than 10 digits is limited to 5, and scaled representation (see Chapter 
3) is used (if required). For example: 


~— Decimal Number Examples 
Le au. } 
1244.4~-__————Fve digits are displayed, and the least 
L2Sgu8 467 significant digit is rounded off. 
Leas 


L2GUnG. 7 


Integer Examples 
L2SUS6 7890 
L2SUES 7890 
L2S4S4 78901 
1. 234s6E10 


Print Width: OPW 


The value of this variable determines the length of the output line for both the 
display and printer. The value can be from 30 to 390. In a clear workspace, 
the value is 64. If this variable is set to a value greater than the length of one 
line across the display, the output will overflow onto the next line. 


If this variable is set to a value greater than the length of one line across the 
printer, an J (O-U-T) symbol is printed in position 132 when the output 
exceeds the print width. 


Notes: 

1. During function definition mode (see Chapter 6), the print width variable is 
automatically set to 128. The variable returns to its original value when the 
function is closed. 

2. When you open, display, and close a function using one statement 
(VFUNCTION [[1}¥), the system uses the current value of the variable. 
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Random Link: ORL 


The value of this variable is used in generating random numbers. The value 
can be from 1 to 23'-2. In a clear workspace, the value is 7*5 (16807). This 
value is changed by the system each time a random number is generated. 


Note: Making ORL local to a user-defined function produces unpredictable 
results. 


Line Counter: DLC 


This variable is a vector. The first element is the function statement number 
currently being executed. The next element is the number of the statement (in 
another function) that invoked the function being executed. The remaining 
elements follow the same pattern. The user cannot set this variable but can 
display it. Attempts to modify DLC are ignored by the system. 


Workspace Available: [WA 


The value in this variable indicates the amount of unused space (the number of 
unused bytes) in the active workspace. The user cannot set the value for this 
variable but can display it. Attempts to modify [IWA are ignored by the 
system. 


Latent Expression: ULX 


A character vector assigned to the latent expression variable is automatically 
executed as an expression by the execute (2) function when a stored 
workspace containing the latent expression is loaded into the active workspace. 


Uses of the latent expression variable include the form LILX«’G’, where a 
function named G is executed when the stored workspace is made active. The 
form OLX«’’’-MESSAGE WHEN WORKSPACE IS MADE ACTIVE’’ displays the 
message MESSAGE WHEN WORKSPACE IS MADE ACTIVE when the stored 
workspace is loaded into the active workspace. 
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Atomic Vector: DAV 


The atomic vector is a 256-element vector that includes all possible APL 
characters. The following example shows how it can be used to determine the 
indices of any known characters in the vector (assuming LIO is 1): 


ava ABC S 
87 89 89 


Appendix B contains a list of the characters in the atomic vector. The most 
common use of the atomic vector is for generating line feed and cursor return 
characters to arrange output. The following example shows how the atomic 
vector can be used to generate these characters. 


The function called NAMES will display your first and last name. Each name 
will start at the left margin, and each character in the name will be one line 
lower than the previous character: 


YAAMESOOVIY 
Yo A NAMES B;OUTPUT; DT; 0;0r0 
es a lO" 
Bee Je Cp, BI+le oe, & 
| ADTATEMENT & CATENATES THE ARGUMENTS TOGETHER 
fF] oAAND ALSO PUTS A BLANK CHARACTER BETWEEN FACH CHARACTER 
l QUTPUTe CC2xJ)p 1 03\05;8),0,8) 
H AaSTATEMENT 8 PLACES A LINE FEED CHARACTER CMAVEL607) 
I ATM EACH BLANK ELEMENT OF OLITPUT 
I OUT PUTER 2%. debe ave iéod 
aan | ASTATEMENT 21 PLACES & CURSOR RETURN CHARACTER CMAVELS 77) 
Ci0T aAFTER THE FIRST NAME 
Rita OUTPUT RSs Teaver S73 
Cl2] aNGW WHEN THE CHARACTER VECTOR QUTPUT IS DISPLAYED, 
DiS aAPL RESPONDS WITH THE APPROPRIATE ACTION WHEN aA LINE 
PLU] aFEED CHARACTER (QAVE14073 OR CURSOR RETURN CHARACTER 
RiSd aC(QAVCiS?) TS ENCOUNTERED IN THE CHARACTER STRING 
Riéd OUTPUT 


“VIROINT A’ NAMES ‘WINTER’ 
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SYSTEM FUNCTIONS 


System functions are used like the primitive (built-in) functions; they are 
monadic (one argument) or dyadic (two arguments) and have explicit results. - 
Following is a list of the system functions and their meanings. A complete 
description of each follows the list: 


System Function Meaning 
type Occ operation Console control 
OCR name Canonical representation 
OFX name Fix 
OEX name Expunge 
ONL class - Name list 
character ONL class Name list beginning with the specified 
character 
ONC name Name classification 


The OCC Function: Console Control 


The OCC function controls some of the interface capabilities between the user 
and the 5110. | 


The OCC function can be monadic (takes one argument) or dyadic (takes two 
arguments). The [ICC function returns an explicit result of 1. when the function 
is successfully executed; otherwise, the result is 0. 


In the monadic form, the [ICC function sets the system to a unique national 
character set (see Appendix C). The right argument must be one of the 
following characters enclosed in single quotes: 


Argument Character Set 

. (period) EBCDIC 

O (zero) International 

1 (one) Austria /Germany 
2 (two) Belgium 

3 (three) Brazil 

4 (four) Denmark / Norway 
5 (five) Finland /Sweden 
6 (six) France 

7 (seven) Italy 

8 (eight) Japan 

9 (nine) Portugal 

+ (divide) Spain 

x (multiply) Spanish speaking 
- (minus) United Kingdom 
+ (plus) French Canadian 


For example, the following instruction sets the system to United Kingdom 
character set: 


Mec 
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In the dyadic form, the DCC function is used to: 


* Turn the display screen off and on during the execution of a user-defined 
function 


« Sound the audible alarm 


* Set the keyboard input to standard APL characters or lowercase alphabetic 
characters 


¢ Scroll the display screen up or down 
e Set the left tab position for printed output 


The left argument is a numeric value that specifies the type of operation. The 
right argument is a numeric scalar or vector that specifies how the operation is 
performed. If the right argument is a vector, the values in the vector determine 
the sequence in which the operations are performed, starting with the first 
element. The operations and the values for the left and right arguments are 
described in the following sections. 


To Turn the Display Screen Off and On During Execution of a User-Defined Function 


Left Right 
Argument Argument Operation 
1 0 Turn the display screen off. 
l 1 Turn the display screen on. 
For example: 

Re 1 eo 6 


turns the display screen off. The display screen remains off until: 

« The LICC function is used to turn the display screen on again. 

e« The user-defined function completes execution. 

¢ The user-defined function requests U0) or | input. 

¢ A function statement that generates displayed output is executed. For this 
reason, the explicit result of the ICC function must be assigned to a 


variable so that the display screen remains off. 


Note: The internal processing capability of the 5110 is increased by 18% when 
the display screen is turned off. 


To Sound the Audible Alarm 


Left Right 
Argument Argument Operation 
2 @) Turns the audible alarm off. 
1 Sound the audible alarm until: 
* The DCC function is used to turn 
the audible alarm off 
e Any key on the keyboard (other than 
the CMD and shift key) is pressed 
2 Sound the audible alarm for 


approximately 1/4 second. 
For example: 


o op eH ype o, va 4 
me, [| (; L, ? wt 2 a 


Ane 


sounds the audible alarm four times for approximately 1/4 second each time. 


To Set the Keyboard Input to Standard APL Characters or Lowercase Alphabetic 
Characters 


Left Right 
Argument Argument Operation 
3 0 Set to standard APL characters. 
1 Set to lowercase alphabetic characters. 


For example: 
OCC 


sets the keyboard input to lowercase alphabetic characters until the keyboard 
input is set to standard APL characters. 


Note: Only the alphabetic keys are affected by the UICC function. 
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When keyboard input is set to lowercase alphabetic characters: 


e Pressing the alphabetic keys enters lowercase alphabetic characters into the 
system. For example: 


ie 4 
A 
enters the character a. 


» When the shift key is held down, pressing the alphabetic keys enters 
uppertase alphabetic characters into the system. For example: 


a 
(= } enters the character A. 


« When the CMD key is held down, pressing an alphabetic key enters the 
APL character that appears on the upper portion of the key. For example: 


a 
enters the character a. 


The lowercase alphabetic characters are used primarily for [1 input. 


To Scroll the Display Screen Up or Down 


Left Right 
Argument Argument Operation 
4 -16 to 16 Move the information on the display 


screen up or down for the specified 
number of lines. 


A positive value in the right argument scrolls the information on the display 
screen up, and a negative value in the right argument scrolls the information on 
the display screen down. 


For example: 
OT mao OS 


scrolls the information on the display screen down 10 lines and then up 5 
lines. 


Note: If a value greater than 16 or less than 16 is specified, the information 
on the display screen is not scrolled up or down, and the explicit result of the 
OCC function is O. 


To Set the Left Tab Position for Printed Output 


Left Right 

Argument Argument Operation 

5 1 to 131 Set the tab print position where the 
first character is printed on the print 
line. 


For example: 
5 eC 4 


specifies that the next output to the printer starts in the sixth position on the 
print line. 


When a tab position is specified, if the line to be printed extends beyond 
position 132, an J (O-U-T) symbol is printed in position 132. Except for the 
1/O error messages (ERROR eee ddd), the specified tab position also 
determines where the error messages are printed on the print line. See 
Appendix F for the error messages. 


The OCR Function: Canonical Representation 


The OCR function formats a user-defined function into a character matrix. This 
function is monadic (takes one argument); the argument for the ICR function 
must be a scalar or vector of characters representing the name of an unlocked 
user-defined function. For example, you have the following user-defined 
function: 


VINTGOLWAV 
VO OReINTG A 


a Read 

ae Led 

CA START: RET AeA 
fc} Teed. 

Cc eCT Ea /START 


v 
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The function INTG is used to create a vector whose length and contents are 
specified by the input argument: 


INTG 
7 ae © Oe PO 
INTG 7 
yaa iad aut Gare ae a 
To format the function INTG into a character matrix and assign the matrix to a 
variable named VAR, you would enter the following instruction: 


VARETCR 'INTG' 


VAR is displayed as follows: 


VAR 
Re INTG &~~——First row is line 0 of the function. 
ReAat 
Ted 
START: RET Tea 
Tete 


2CLTead /START 
o¥ A R+—— Indicates VAR is a 6-row, 12-column matrix. 
6& 12 


Notice that the line numbers are removed along with the opening and closing 
V. Also, labels within the function are aligned at the left margin. 


Now you can change matrix VAR by simply indexing the elements: 


VARY; 12¢' [ '~—The element in row 4, column 12 is changed to I. 
¥AR 

Re INTG A 

ReAp) 

Ted 

START: RET V¢T 

ted 

+OTS ay /START 


To format a matrix created by the OCR function into a user-defined function, 
use the LJFX function. The DFX function is discussed next. 
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The DJFX Function: Fix 


The OFX function forms (fixes) a user-defined function from a character matrix 
(that was most likely formed by the OCR function). This function is monadic 
(takes one argument); the argument for the OFX function is the name of a 
matrix to be formed into a user-defined function. If an error is encountered 
(invalid character or missing single quote, for example) as the matrix is being 
formed into a user-defined function, the operation is interrupted, the number 
of the row in error minus one is displayed, and no change takes place in the 
active workspace (the user-defined function is not formed). 


To show how the OFX function works, we will use the matrix created in the 
previous example (see the ICR function). To form matrix VAR into a 
user-defined function, enter the following instruction: 


FX ¥AR APL responds with the name of the 
IN —— user-defined function. 


The OFX function produces an explicit result (the vector of characters that 
represents the name of the user-defined function), and the original definition of 
the user-defined function (if there was one) is replaced. 


Now the function INTG can be displayed and executed: 


VINTGLOIYV 
Y ReINTG &A 
Rea ef 


Eda 
Ceo Tus 
C31 START: RETI¢T 
Ce Tete 
ae eC Tia /START 
V 
INTG & 
be eS 
INTG & 


12345 6 7 8 
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Following is an example that shows how the DCR and (FX functions can be 
used to modify the definition of a function within another function. This 
example will use the following user-defined function: 


VINTGEROIY 
Y Re INTG A 
Ci Re Apt 
p20 Led 
P31 START: RET TA 
ry. Te ted 
CS CT EA /SSTART 
v 


INTG & 
ood bp lp 


Format the function into a matrix: 


MeqCR ‘ INTG '~+— Canonical Representation 


ReEINTG & 

Re AGO 

Te] 
START: RET Ie4 
Le D+ 


4CT EA) /START 


Now, define a function called CHANGE, which, when performed, will execute a 
modified version of INTG. 


VO CHANGE ; INTO; %—INTG is made a local function so that the 


1 l MC id i Lede Tt global version will not be changed (the 
I = ‘ Ye te x local version will not exist after the 
[3c INTO | execution of CHANGE is complete). 
y 
Assign the explicit result of the DFX 
function to Y so that it will not be 
displayed. 
Execute the modified version of INTG. 
TNTG 4.~+-—\—— Execute INTG. 
Wap apy. 
CHANGE Execute CHANGE. 
L 2 3 Y 
INTG W.-~———_- Execute INTG again. 
eS ee 8 


The (EX Function: Expunge 


The OEX function erases global objects or active local objects specified by the 
argument from the active workspace (unless the object is a pendent or 
suspended function). This function is monadic (takes one argument); the 
argument must be a scalar, vector, or matrix of characters. 


Thus, if object AB is to be erased, the following instruction would be entered: 
MEX AS 


Note: Even after the object is erased, the name remains in the symbol table 
(the part of the active workspace that contains all of the symbols used). To 
clear unused symbols from the symbol table, save and then reload the 
workspace. 


The MEX function returns an explicit result of 1 if the name is available and a O 
if it is not available or if the argument does not represent a valid name. When 
the QEX function is applied to a matrix of names (each row represents a 
name), the result is a logical vector (zeros and/or ones) with an element for 
each name. The [JEX function is like the )ERASE command, except that it 
applies to the active referent (see Chapter 6, Local and Global Names) of a 
name. 


Note: If the object being expunged is a shared variable (see Chapter 7), it will 
be retracted. 


The ONL Function: Name List 


The ONL function yields a character matrix; each row of the matrix represents 
the name of a local (active referent) or global object in the active workspace. 
The ordering of the rows has no special significance. The DNL function can be 
either monadic (takes one argument) or dyadic (takes two arguments); in both 
the monadic and dyadic forms, the right argument is an integer, scalar, or 
vector that determines the class(es) of names that will be included in the 
result. The values for the input argument and associated classes of names are: 


Argument Name Class 


1 Names of labels 
2 Names of variables 
3 Names of user-defined functions 


It does not make any difference in what order the class of names appears in 
the argument. For example, INL 2 3 or ONL 3 2 results in a matrix of all the 
variable and user-defined function names. 
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In the dyadic form, the left argument is a scalar or vector of alphabetic 
characters that restricts the names produced to those with the same initial 
character as that of the argument. For example, ‘AD’ ONL 2 results in a matrix 
of all the variable names starting with the characters A and D. 


Uses of the DNL function include: 


¢ Erasing objects of a certain class (and also beginning with a certain 
character). For example: 


NEX "BR" [NL 2 


erases all the variables whose names start with B. 


« Avoiding the choice of a name that already exists. 


The ONC Function: Name Classification 


The ONC function is monadic (takes one argument); the argument is a scalar 
or array of characters. The result of the function is a vector of numbers 
representing the class of the name given in each row of the argument. The 
classes of names are as follows: 


Result Meaning 
@) Name is available for use 
1 Name of a label 
2 Name of a variable 
3 Name of a function 
4 Name is nonstandard (not available for use) 
For example: 
TNC | AVERAGE 
3 


OE oes result indicates that the name AVERAGE is 


the name of a user-defined function. 
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Chapter 6. User-Defined Functions 


APL provides an extensive set of primitive functions; nevertheless, you may 
want a function to solve a special problem. APL provides a way to create a 
new function, called function definition. During function definition, you use 

existing APL functions to create new functions called user-defined functions. 


Normally, the 5110 is in execution mode; that is, after a line has been entered 
and the EXECUTE key pressed, the 5110 executes that line. To define a 
function, the mode must be changed to function definition mode; after the 
function is defined, the mode must be changed back to execution mode before 
the function can be executed. You change the mode by entering the V (del) 
symbol. The first V changes the mode to function definition mode; the second 
V indicates the end of function definition and changes the mode back to 
execution mode. 


No statement error checking is performed during function definition mode. 
That is, all error checking is performed when the statement is executed. 
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MECHANICS OF FUNCTION DEFINITION 


The following steps are required to define a new function: 


1. 


Enter a V followed by the function header (see Function Header in this 
chapter). After the function header is entered, APL responds with a [1] 
and waits for the first statement of the function to be entered: 


YHOME SCORE VEST TOR (function header) 
ie ge 
Enter the statements that define the operations to be performed by the 


function. As each line is entered, APL automatically responds with the 
next line number: 


¥ HOME SCORE ¥ISTTOR 


ae ia “THE FINAL SOORE TS: ' 
eae + / HOME 
PAC ar ee 
[uy “y +/VISTTOR 
Notes: 


1. Since problems can occur when you are editing statements that 
exceed the print width (see IIPW system variable in Chapter 5), during 
function mode, the print width is automatically set to 128. This 
permits statements up to a maximum of 115 characters in length to be 
placed on the input line (lines 1 and 0) and edited. Editing statements 
are discussed later in this chapter. The print width returns to its 
original value when the function is closed. 

2. When you open the function definition, display the user-defined 
function, and close the function definition using one statement (see 
Reopening Function Definition in this chapter), the system uses the 
current value of JPW. This allows user-defined functions with long 
statements to be printed on narrow paper. 

3. If a user-defined function contains a statement that is greater than 
115 characters in length, that statement cannot be edited and the 
function cannot be written on the media. (See OCR and DFX in 
Chapter 5 for information on changing a user-defined function to a 
matrix.) 


Enter another V when the function definition is complete. The closing V 
may be entered alone or at the end of a statement. For example: 


Me +/VISTTORV 
or 
Ped v 
Note: If the closing V is entered at the end of a comment statement, 


which begins with a A symbol, the V will be treated as part of the 
comment and the function will not be closed. 


Function Header 


The function header names the function and specifies whether a function has 
no arguments (niladic), one argument (monadic), or two arguments (dyadic). 


Note: Function names should not begin with SA or TA because SA and TA 
are used for stop and trace control (Stop Control and Trace Control! are 
discussed later in this chapter). 


The function header also determines whether or not a function has an explicit 
result. If a function has an explicit result, the result of the function is 
temporarily stored in a result variable (names in the function header) for use in 
calculations outside the function. The result variable must be included in the 
result statement (the statement that determines the final result of the function) 
as well as the function header. For example: 


Result Variable 


Vo RESULTEX PLUS 
rad REGUL Le xX +7 ¥ 
4 PLUS & 


y 


The result of the function is 


4 temporarily stored in the result 
10473 PLUS tu variable so that it can be used 
17 by another function. 


User-defined functions that do not have an explicit result cannot be used as 
part of another expression. For example: 


VX PLUS] Y 
nad x+¥V 

LO0+3 PLUSLT 4 
7 
VALUE ERROR 

1043 PLUST 4 


rn 


The following table shows the possible forms of the function header: 


Number of Format of Header 
Arguments | Type No Explicit Result | Explicit Result 
0. Niladic 
1 Monadic 
2 Dyadic 


VNAME VR«NAME 
There must be a blank between the function name and the arguments. Also, 


VNAME B VR«NAME B 
VA NAME B VR«A NAME B 

the same symbol cannot appear more than once in the function header: thus, 

Z+FUNCTION Z is invalid. 


For user-defined functions, the order in which the arguments are entered is 
important. For example, assume that Z<X DIVIDE Y represents a function in 
which Z is the result of XY. Now if 20 DIVIDE 10 is entered, the result is 2. 
However, if 10 DIVIDE 20 is entered, the result is 0.5. 
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Branching and Labels 


Statements in a function definition are normally executed in the order indicated 
by the statement numbers, and execution terminates at the end of the last 
statement in the sequence. This normal order can be modified by branching. 


Branching is specified by a right arrow (+) followed by a label (name) that 
specifies the statement that is to be branched to. For example, the expression 
+START means branch to a statement labeled START. When a label is 
assigned to a statement, the label must be followed by a colon (:) and must 
precede the statement. The colon separates the label from the statement: 


[27 START: NeN+d 


a 


CS 2aTAaAry 


In the previous example, the label START is assigned to the second statement 
in the function. In other words, START has a value of 2; however, if the 
function is edited and the statement is no longer the second statement in the 
function, START will automatically be given the value (or statement number) of 
the new statement. (See Function Editing later in this chapter.) 


Labels are local to a function—which means they can be used only within that 
function. Following are some additional rules that apply to the use of labels: 


« They must not appear in the function header. 
« You cannot assign values to them. 

e They can be up to 77 ee in length. 

« They cannot be used on comments. 


« When duplicate labels or labels that duplicate a local name are used, the 
first use of the label or name is the accepted use. 


If the branch is to zero (+0) or any statement number not in the function, the 
function is exited when the branch statement is executed. If the value to the 
right of the > is a vector (for example, +L1,L2,L3), the branch is determined 
by the vector’s first element. If the vector is an empty vector (there are no 
elements), the branch is not executed, and the normal sequence of statement 
execution continues. For example, the conditional branch >+(I>N)/START is 
evaluated as follows: 


l: First, the condition (I>N) is evaluated: the result is 1 if the condition is 
true and O tf the condition is false. 


2. The result of step 1 is then used as the left argument for the compress 
(A/B) function: 
a. If the result of step 1 was 1, START is selected from the right 
argument and a branch to the statement labeled START is taken. 
b. If the result of step 1 was 0, nothing is selected from the right 
argument (an empty vector is the result), and the sequence of 
execution falls through to the next statement. 


Following are three examples of defining and using a function to determine the 
sum of the first N integers. Each function uses a different method of 
branching. Remember, the expression to the right of the > is evaluated, and 
the result determines to what statement the branch is taken: 


YO S¢SUM. MN 


ee Be Se 0 
an Led. 
Ca CHECK : #LAGEL * T=N~-— Branch to LABEL if 1<N; otherwise, 
CY 7] LABEL: SeS+ 7 exit the function. 
a Lele 
eee SCHECKE Y 
SUM1 
LS 
¥ S¢SUMS WN 
rid Seo 
an Led 
[3 CHECK 2-0 0 >N 3 / f1<—-——Branch to 0 (terminate the function) 
ae hare ke a | or fall through. 
Seam (4 ed 
fr é o SQlHECK ¥ 
SUM2 & 
LS 
YO SeS LMS WN 
Cac 
fo 
3c CHECK : S¢S+] 
I LeT+1 
se: CT 2N0 “CHECK ¥—+———Branch to CHECK or fall through. 
TG ts oe aumeer 
a lee 
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Several forms of the branch instruction are shown in the following table: 


Branch Instruction Result 

“LAGEL Branches to a statement labeled LABEL 

30 Exits function 

SLABEL X Xx ¥ Branches to LABEL or exit function 
sCCKeYD, CX VD. OXY) ISL LE LS Branches to L1, L2, or L3 

SCL Lote x= ¥ 7 Branches to L1 or L2 

SCXRY I/O) Exits function or falls through to next statement 
eCXeY) /LABEL 

2 (Xs) pLAREL, } Branches to LABEL or falls through 


Note: Branching will also work if a specific statement number is specified to 
the right of the +. For example, +3 means branch to statement 3; or 
+X<3xA means X is assigned the value of 3 times the value of A, and the 
value of X is then used as the branch to statement number. However, these 
forms of branching (using statement numbers instead of labels) can cause 
problems if the function is edited and the statements are renumbered. 


Local and Global Names 


A local name is the name of a variable or user-defined function that is used 
only within a particular user-defined function. A global name is the name of a 
variable or user-defined function that can be used within a user-defined 
function and can also be used outside of it. An example of the use of a local 
variable name would be the name of a counter used in a user-defined function 
(which is not required for any use outside the function). 


To make a name local to a user-defined function, it must be contained in the 
function header. For example, the function header VZ«EXAMPLE X;J:1 
establishes the result variable Z, the argument X, and variable J and | as local 
variables. Notice that the local names, other than the result variable and 
arguments, follow the right argument (if any) and are preceded by semicolons. 


A local name can be the same as a global name (variable or user-defined 
function) or a local name in another function. However, any reference to the 
name local to the function will not change the values of any other global or 
local objects (variables or user-defined functions) or cause them to be used. 
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After a user-defined function has executed, the following rules apply to the 
local and global variables used by the function: 


e Any value assigned to a local variable is lost. 


e If a local variable had the same name as a global variable, the value of the 
global variable remains unchanged. 


e If the value of a global variable was changed by the function, it retains the 
new value. 


For example: 


LOle Log 
GLOBE LOG 
YRESULT¢E XAMPLE | LOO; & 
Rd Laie So 
Ce xe 2S 
had GLOBE Lo 
Cue) RESUL Te LOl+ GLO + xy 
EXAM PAE 
x—————_ X has no value after the function has executed. 
VALUE ERROR 
x 
A The global value associated with this name was 
1 unchanged by the function. 
100 
(L.{1 ~———— The global value was changed by the function 
La because the name GLOB was not made local to 
the function. 


Because the value of a local name disappears as soon as execution of the 
function finishes, the only time you can use or display the value of a local 
name is while the function to which it belongs is still executing, is suspended, 
or is pendent. 


Note: tf a name is local to a function that calls another function, the value of 
that local name can also be used by the called function. 
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A name local to a function that has not completed execution or that is 
suspended will be inaccessible if the name is also local to a more recently 
called function. Putting it another way, the value of a name that you can use 
or display is always the most recent local value of the name. Of course, as 
execution of the more recently called functions is completed, the next earlier 
value of each local variable will again be accessible. A name can therefore be 
said to have one active referent or value, and possibly several /atent referents 
or values. For example: 


Vo TIAN; XX 
rad XXe 100 
Ca. “THE FUNCTION TIAN GIVES XX THE VALUE’ 
tao XX 
Lr te oI "AND CALLS THE FUNCTION DAVE" 
Co DAVE 
és a "WHEN TAVE IS THROUGH EXECUTING AND EXECUTION RETURNS ° 
Po "TO DAN, AX ONCE AGAIN HAS THE VALUE 
om RXV 


VoTAVE | Xx 
na AXe 200 
eae “THE FUNCTION DAVE GIVES XX THE VALUE * 
io xX 
[he "ANT CALLG THE FUNCTION JERRY’ 
fea PT JERRY 
né] "WHEN JERRY 7S THROUGH EXECUTING ANT EXECUTION RETURNS * 
eo "TO DAVE. XX ONCE AGAIN HAS THE VALUE * 
18 AAV 


VY JERRY 5 xXx 
ak XX S00 
“l “THE FUNCTION JERRY GIVES XX THE VALUE" 
“I XX 
wl "ANT RETURNS TO CAVE ¥ 
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TIAN 
THE FUNCTION DAN GIVES XxX THE VALUE 


100 

AND CALLS THE FUNCTION TAVE 

THE FUNCTION DAVE GIVES XX THE VALUE 
2 0 


ANY CALLS THE FUNCTION JERRY 

THE FUNCTION JERRY GIVES XX THE VALUE 

300 

AN RETURNS TO CAVE 

WHEN JERRY IS THROUGH EXECUTING AND EXECUTION RETURNS 
TO WAVE, XX ONCE AGAIN HAS THE VALUE 


200 
WHEN DAVE IS THROUGH EXECUTING AND EXECUTION RETURNS 
TO DAN, XX ONCE AGATN HAS THE VALUE 
100 
xx 
VALUE ERROR 
XX 
“4 


The )SINL command causes the SINL list (state indicator with name list; see 
the ONL function in Chapter 5) to be displayed. The SINL list contains a 
complete set of referents of a name. 


Note: See System Functions in Chapter 5 for an example of a local 
user-defined function using the DIFX system function. 


If the SINL list is scanned downward, the first occurrence of a variable name is 
its active referent. If the name appears again, it is a latent referent. Global 
names are not found in this list; they can be displayed with the )VARS 
command and )FNS command. 


In the following SINL display, variable P has referents as follows: 


2S 0NL 
Gov] «ez xX iT 
oe oe  j}—_——. The active referent of P is local to function F. 
Q°S] “#0 X T 
RE 2c P-——__-———- First latent referent of P is local to function R. 
G3 2 2% I 
As the state indicator is cleared, jatent referents become active. 
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INTERACTIVE FUNCTIONS 


User-defined functions can display messages and/or request input from the 
keyboard. The messages (character data) in the user-defined function are 
enclosed in quotes. The L] (quad) and { (quad quote) symbols are used to 
request input from the keyboard during function execution. The following 
function is an example of an interactive function that computes the amount of 
interest on a capital amount for a given number of years: 


YoY 
] ‘ENTER THE CAPT TAL AMOUNT TN TIOLLARS ' 
i ef] 
eds "ENTER THE INTEREST IN PERCENT’ 
7] tet] 
wed "ENTER THE PERTOU IN YEARS ' 
(6) Yet 
1 "THE RESULT I[S° 
| AxXCL+O, 0) 2T 4¥V¥ 


Cl 
ENTER THE CAPITAL AMOUNT IN DOLLARS 


: 
100 
ENTER THE INTEREST IN PERCENT 
[}: 
ENTER THE PERTOO IN YEARS 
(}: 
3 


seiket DS 


THE RI 
Lié. & 
Cal 
ENTER THE CAPITAL AHQUNT IN TOLLARS 
tT: 
La00 
ENTER THE INTEREST IN PERCENT 
Hs 
3.88 
ENTER THE PERTOO TH YEARS 
l owe 
THE RESULT TS 


apres Pon 
I. a a U ‘ wn 


Requesting Keyboard Input during Function Execution 


The (] (quad) appearing anywhere other than immediately to the left of the 
assignment arrow indicates that keyboard input is required. When the [] is 
encountered in the function, the two symbols 0): (a quad symbol followed by 
a colon) are displayed, the display is moved up one line, and the cursor 
appears. The quad and colon symbols are displayed to alert the user that input 
is required. Any valid expression entered at this point is evaluated, and the 
result is substituted for the quad. You can escape from a quad input request 
by entering the right arrow >. 


An invalid entry in response to request for input results in an appropriate error 
message, and the request for input is made again. Any system commands 
entered will be executed, after which the request for input will again be made. 
An empty input (no keying) is rejected, and the 5110 again displays the 
symbols 1): and awaits input. 


When the quad quote [] (a quad overstruck with a quote) is used, input from 
the keyboard is treated as character data. The input begins at the left margin 
of the display; quotes do not need to be entered to define the data as 
character data. When [ input is requested, the symbols 0: do not appear as 
they did with a UJ input request. The input is entered after the flashing cursor 
appears on the screen. For example: 


xe 


CANS T 


x 
CAN'T 

Xet 
'CAN' OT! 
‘CANT OT! 


Anything you enter in response to a quad quote request for input is considered 
character input. Therefore, if you enter a system command or a branch arrow 
(+) to terminate the function, the entry is treated as character data for the 
function, and the system command or branch will not be executed. This can 
be a problem if you are trying to escape from a quad quote input request. 
Therefore, APL provides an escape for this situation. To escape from a quad 
quote input request, enter the J symbol by holding the CMD key and pressing 
the key. The function is interrupted, and the function name and the line 
+ 


number being executed are displayed. You can then modify the function or 
terminate it by entering the right arrow >. 
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ARRANGING THE OUTPUT FROM A USER-DEFINED FUNCTION 


The output from user-defined functions can be arranged by the format function 
(see the ¢ function in Chapter 4) or bare output. Bare output is discussed next. 


Bare Output 


After normal output, the cursor is moved to the next line so that the next entry 
(either input or output) will begin at a standard position. However, bare output, 
denoted by the form ['J«X (X can be any expression), does not move the 
cursor to the next line. Therefore. more than one variable or expression can be 
displayed on the same line. For example: 


bribes: Uy 

[es 
He” “TiIMNES 
i oat g 
Ee ds 
ean) 

e¢ TTRES We 

2 bee Ab LS 8 


Ceacies® ~aieaiey’ “Tpocoecg 9 Yah tape: 
ie 

Ce ar ene aT Ieee | 3 

foe i ee Ga oe fees ee 


Because the cursor does not return to the next line after bare output, when 
quad quote (/']) input is entered following the bare output, the input starts after 
the last character of the bare output. Then when the input is processed, it is 
prefixed by any bare output cn the input line. For example: 


VOUTPOPA LH PLT 


Pu oe THiS te Bake. OPE ih 

Pel afHe WEST STATEMENT REQUESTS © INPUT 
Lora Nee 

aT aNOk OL SPLAY THE THPUT 

Lot 


HUY PUTATA PUT 
THiS PT BARE OLITPLIT! | | u-—The cursor appears here. Now 
enter THIS 1S [] INPUT. 
THIS TS BARE OQUTPUTIIEITHIS 15 0 INPUT 
After EXECUTE is 
pressed, the output 
line looks tike this. 


Therefore, if quad quote input follows bare output (but only the input is to be 
processed), the bare output must be removed from the input line. Following is 
an example of a function that will remove the bare output: 


VREBAREAOUTPUT MSG;TO; J 

Cid Orde. 

C27 Hense 

C3] aCHECK THE BARE OUTPUT FOR EMBEDDED CURSOR RETURNS 
Ced Je 714 ¢0MSG) AVES TI | 
CSI alROP ANY BARE OUTPUT PREFIX. FROM THE INPUT 

C60 Reccéul de L411) 409 


This is how the function works: 


YOUTATN The Bare Output 
Ric) GAREAOQUTPUT (THIS TS BARE QUTPUTEEE' 
Niece ae “this function will remove the bare output. 


QUTATN 
THIS TS BARE OUTPUT! ! ! -The cursor appears here. Now enter THIS IS [T] INPUT. 


THIS TS BARE QUYTPUTIEITHTS TS © INPUT 


THIS IS & INPUT +—— This is the final result. 


“. 


If bare output consists of a character vector and backspace characters, the 
display screen is scrolled down one line when the number of backspace 
characters is greater than the number of characters in the character vector. For 
example: 


D1Io+1 
[<(10p’A’), 119 DAV[ 159] ~————— Backspace Character from the 
Atomic Vector. 


LOCKED FUNCTIONS 


A locked function can only be executed, copied, or erased; it cannot be revised 
or displayed in any way, nor can trace control and stop control (see Trace 
Control and Stop Control later in this chapter) be changed. A function is locked, 
or protected, when the function definition is opened or closed with a V(V 
overstruck with ~) instead of a V. 


When an error is encountered in a locked function, execution of that function is 
abandoned (not suspended). If this function was invoked by another locked 
function, execution of the second function is abandoned also, and so on, until 
either (1) a statement in an unlocked function or (2) an input statement is 
reached. Then an error message is displayed. In the first case, the execution 
of the unlocked function is suspended at the statement; in the second case, 
the 5110 waits for input. 


Note: A locked function cannot be unlocked; therefore, if the function contains 
an error, the function cannot be edited and the error corrected. 
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FUNCTION EDITING 


Several methods are used when the system is in function definition mode to 
display and revise a user-defined function. Also, after a function definition has 
been closed, the definition can be reopened and the same methods used for 
further revisions or displays. (See Reopening Function Definition in this chapter.) 


Displaying a User-Defined Function 


Once the system is in function definition mode, part or all of a user-defined 
function can be displayed as follows: 


¢ To display the entire function, including the function header and the opening 
and closing V, enter [01]. APL responds by displaying: the function, then 
waiting for the entry of additional statements. 


* To display from a specified statement to the end of the function, enter 
[Un], where n is the specified statement number. APL responds by 
displaying the function from statement n to the end of the function, then 
waiting for the last statement displayed to. be edited (see Editing Statements 
in this chapter). 


* To display only one statement of the function, enter [n{]], where n is the 
statement number to be displayed. APL responds by displaying statement n 
and waiting for the statement to be edited (see Editing Statements in this 
chapter). 


The following table summarizes function display when the system is in function 
definition mode: : 


Entry Result 

[O}] Displays all statements 

[On] Displays all statements from n onward 
{nO} Displays statement n 
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Revising a User-Defined Function 


Statements in a user-defined function can be replaced, added, inserted, 
deleted, or edited as follows: 


¢ To replace statement number n, enter [n] and the replacement statement. 
If just [n] is entered, APL responds with [n], then waits for the 
replacement statement to be entered. If the function header is to be 
replaced, enter [0] and the new function header. 


¢ To add a statement, enter [n] (n can be any statement number beyond the 
last existing statement number) and the new statement. APL will respond 
with the next statement number, and additional statements can be entered if 
required. 


¢ To insert a statement between existing statements, enter [n] and the new 
statement. n can be any decimal number with up to four decimal digits. For 
example, to insert a statement between statements 8 and 9, any decimal 
number between 8.0000 and 9.0000 can be used. APL will respond with 
another decimal statement number, and additional statements can be 
inserted between statements 8 and 9 if required. (These and the following 
statements are automatically renumbered when the function definition is 
closed.) 


Note: The statement number 9999.9999 is the last valid statement number. 


¢ To delete statement n, enter [An] or display statement n, press the ATTN 
key to delete the line, and then press the EXECUTE key. 


Note: The [An] and closing V cannot be entered on the same line. If the 


function definition is to be closed immediately after a statement has been 
deleted, the closing V must be entered on the next line. 
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« To edit a specific statement, use the following procedure: 


1. Enter [nL] (where n is a statement number). Statement n is 
displayed. 


Note: The scroll keys 8 Fa can be used to position a 


statement on the display screen to the input lines O and 1 for editing. 
To do this, use the scroll down ( ) key to position the 


statement to lines O and 1. If the statement does not require two 
lines, position the statement on line 1 and make sure another 
statement is not displayed on line O. 


2; Choose one of the following options: 
a. To change a character, position the cursor (flashing character) at 
the character to be changed. Enter the correct character. 
b. To delete a character, position the cursor at the character to be 
deleted. Then press the backspace ( ) key while holding 


the command (CMD) key. The character at the cursor is deleted 
from the line, and the characters that were to the right of the 
deleted character are moved one position to the left. 

c. To insert a character, position the cursor to the position where the 
character is to be inserted. Then press the forward space 
‘B ) key while holding down the command (CMD) key. The 


characters from the cursor position to the end of the line are moved 
one position to the right. For example: [1] A«1245 should be [1] 
A+12345. Position the cursor at the 4, and press the forward 
space and command (CMD) keys simultaneously. The display will 
look like this: [1] A«+12__ 45. Now enter the 3. 

d. To delete all or part of a line, press the ATTN key to delete 
everything from the cursor position to the end of the line. 


3. Press the EXECUTE key. The next statement number is displayed. 


Note: If more than one statement number is entered on the same line, only 
the last statement number is used. For example, if a line contained [3] [8] 
[4] ‘NEW LINE’, only statement 4 is replaced when the EXECUTE key is 
pressed. 


Reopening Function Definition 


If you want to edit a function that has previously been closed, the function 
definition must be reopened. For example, if function R is already defined, you 
reopen the function definition for function R by entering VR. The rest of the 
function header must not be entered or the error message DEFN ERROR is 
displayed and the function definition is not reopened. The 5110 responds by 
displaying [n+1], where n is the number of statements in R. Function editing 
then proceeds in the normal manner. 


Function definition can also be reopened and the editing or display requested 
on the same line. For example, VR[3]S«S+1 edits the function by entering 
the new line 3 (S<S+1) immediately. Then the 5110 responds by displaying 
[4] and awaiting continuation. The entire process can be accomplished on a 
single line: VR[3]S<S+1V opens the definition of function R, enters a new 
line 3, and terminates function definition. VR[O]V causes the entire definition 
of R to be displayed, after which the 5110 returns to execution mode. 

Note: You cannot reopen the definition of a function, delete a statement, and 
close the function (for example, VR[ A4]V) on the same line, because the 
closing V cannot be on the same line as the [ An]. 

When an error occurs in a function, the function name, the line number, and 
the statement in error are displayed. A caret on the following line indicates 
where the 5110 stopped execution of the statement. The statement in error 
can be corrected as follows: 

1. Scroll down until the caret is removed from the screen. 

2. Scroll up one line. 

3. Insert a V before the function name. 

4. Correct the error in the statement. 

5. Place a V after the statement. 


6. Press the EXECUTE key. 


This procedure works only if the complete statement is displayed. 
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An Example of Function Editing 


In this example, the user-defined function AVERAGE is used to show how the 
methods used to revise and display functions work: 


VAN ao ke t aif aE x —-- OO or De fine the function. 
"THIS FUNCTION CALCULATES AVERAGES ' : 
HARE CES AEX DY 
AVERAGE 2 4 4 Ecce and test the function. 


FUNCTION CALCULATES AVERAGES 


WAVE RAGE h s7 UPI AVE RCE: Se ait octet, 


Display statement 1. 


"THIS FUNE TION CALCULATES AVERAGES ' 

“THIS FUNCTION CALCULATES AVERAGES ANT SUMS —~—statement 1 was edited 
P31 ‘THE SUM_IS' to look like this. 
bARY Oe, statements 3 and 4. 

VAVE RAGE LI I-—#£ ie —_ _ Display the function. 
v Ay ERAGE x 

THIS FUNCTION CALCULATES AVERAGES Ant SUMS 
‘THE AVERAGE IS' 
eae. fe 
‘THE SUM IS' 


. ro ra * 


AVERAGE 2M 6 Beate average. 
FUNCTION CALCULATES AVERAGES AND SUMS 
AVERAGE IS 


SUM IS 


VAVERAGE [SI +/X4o————_———_______________ rn lace statement 3. 
esas Meth ease get oe ee eS statement 1. 
COJAVERAGEASUM XV¥+—————____—___ rap ace the function header. 
FAVE RAGEASUME [1 ¥-——_————________ pjgplay the function. 
Y AVERAGE ASUM 
“THE AVERAGE Is' 


“THE SUM IS - 


pace 
bER 


AVERAGEASUM 2 4 @ 8 
A VE RAGE Ot 


SUM TS 


FAVE RAGE ASUM CUS IY ———c—————______________—- psp lay the function from 


“THE SUM IS¢ statement 3 to the end. 


es 


TRACE AND STOP CONTROLS 


APL provides the ability to trace or stop execution of user-defined functions, 
providing the functions are not locked (see Locked Functions in this chapter). 


Trace Control 


Trace control is used to display the results of selected statements as a function 
executes. The display consists of the function name followed by the number 
and results of the selected statement. For example: 


STEVE[ 1] 2<———— Result 


Function Statement 
Name Name 


Statements to be treated are specified by a trace vector. The format of the 
trace control function is TA STEVE<V, where STEVE is the name of the 
function and V is the vector specifying the statement numbers to be traced. 
For example, if TA STEVE«<2 3 5 is entered, the statement 2, 3, and 5 are 
traced each time function STEVE is executed. TA STEVE+10 must be entered 
to discontinue the tracing of function STEVE. To trace each statement of the 
function, enter TA STEVE<1N, where N is the number of statement in the 
function: 


YOTEVE I 
1 AGL XT 
wl BeQxy 
Lad Ce Sx y 
We] Tie le xT 
wal AERC ET 
STEVE 2 


TASTEVE® 14 
STEVE 2 Trace the first four statements 

STEVEC LI 2 in function STEVE. 

STEVE 20 Ut 

STEVES] 4} 

STEVE I & 

2 
TASTEVE © 2 Trace statement 2 in function STEVE. 
STEVE 2 

STEVEL 2] 4 

20 . 
TASTEYVIE¢ 1 0 +——— Discontinue tracing in function STEVE. 
STEVE 2 

20 


User-Defined Functions 


Trace control can also be set by statements within a function. These 
statements initiate tracing when a variable contains a certain value. For 
example: 


VSTEVECOQIUV 
V STEVE. J 


4 At Lx] 

22 TASTEVE & 3 X = 2 ~——- Trace statement 3 in function STEVE 
4 ex when A equals 2. 

2] Lie ty x 

Debt Atl+nh 


STEVE 2 
STEVEL3Z] 6 
Lé 

STEVE 3 


ol 


Note: The following instruction establishes trace control for the first statement 
of each user-defined function in the active workspace: 


2 de. (Oe oT ATL COCCTINL Sd. @ OT 


This instruction can be used to find out what functions are called by another 
function. 


The following user-defined function named TRACE establishes a trace vector 
for each statement in a specified user-defined function: 


YTRACE NAME 
Pid a TA'LNAME. “@éa,itelCR' CNAME. CCCP 
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When the function TRACE is executed, the argument must be entered in single 
quotes. For example: 


VETEVEC TAY 
¥ SPEVE: a 


a Ae 1 xT 
i he 2x T 
[42] Ce sxT 
fy] Tiel x 7 
edad Ae he et 
v 
TRACE "STEVE '~— Establish a trace vector for each 
STEVE 2 statement in function STEVE. 
STEVEELI 2 
STEVES] 4——————_———. Each statement of function 
STEVER SI 6 STEVE has been traced. 
STEVECUT 8 
STEVELS I 20 


TASTEVE 10 
STEVE 2 


Stop Control 


Stop control is used to stop the execution of a function just before specified 
statements. At each stop, the function name and statement number of the 
statement to be executed next is displayed. The statements are specified by a 
stop vector. The format of the stop control function is SA STEVE<V, where 
STEVE is the name of the function and V is the vector specifying the 
statements. After the stop, the system is in the suspended state; to resume 
execution, >ULC must be entered (see Chapter 5). SASTEVE+10 (STEVE is 
the function name) must be entered to discontinue the stop control function. 


Stop control can be set by statements within a function. These statements 
initiate halts when a variable contains a certain value. For example, SA 
STEVE+4xN>8 means stop before statement 4 in function STEVE when N is 
greater than 8. 


Trace control and stop control can both be used in the same user-defined 
function. An attempt to set trace control or stop control for a nonexistent 


function creates a variable and causes a syntax error. For example: 


ICLEAR 


CLEAR WS 

DARE L 2 
SYNTAX ERROR 

Seb ed 2S 


VARS 
F 
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Chapter 7. Tape, Diskette, Display Screen, and Printer Input and Output 


When input and output involve the tape, diskette, display screen, or printer, an 
APL shared variable can be established as the connection between the active 
workspace and the I/O processor. That is, the value of the shared variable is 
shared between the active workspace and the !/O processor. 


There are two types of input/output operations: sequential access to tape and 
diskette files, and direct access to diskette files and the display screen. There 
is also an output operation to the printer. Sequential access means that the 
records must be written to and read from the data file in sequential order. 
Direct access means that specified records are directly read from or written to 
the data file or display screen. 


Input and output operations require the followigg steps: 

1. Make a shared variable offer. 

2. Specify the operation to be performed. 

3: Transfer the data (perform the input/output operations). 
4. Terminate the operation. 


5. Retract the shared variable offer. 


MAKING A SHARED VARIABLE OFFER 


To establish a shared variable between the actvie workspace and the I/O 
processor, the LISVO (share variable offer) system function is used. This 
function is dyadic (requires two arguments), where the left argument is a 1 
(which specifies the 5110 I/O processor) and the right argument is character 
data that specifies the variable name(s) being offered as a shared variable. The 
5110 allows up to 12 variable names to be shared. These variable names can 
be offered in one or more statements. However, if more than one name is 
used as the right argument of the DSVO function, the names must be entered 
as a character matrix with each row representing one name. For example: 


1 G8VO 4 do oe ABCIN 
or Each row represents a separate variable name. 


ft fh iM i Oh be ly. 1 Fa ‘ ra. ia (" ti 1 
1 (S¥0 NAMES 
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Direct access input and output operations require a pair of shared variables. 
One variable name must start with the characters CTL, and the other name 

must start with the characters DAT. After the first 3 characters, the next 15 
characters in each pair of names must be identical. For example, 1 USVO 2 
40 ‘CTLXDATX’ offers CTLX and DATX as shared variables. 


The explicit result of the OSVO system function is a 2, 1, or O for each 
variable name offered to be shared. For example: 


1 (8V¥0 4 Le ABCT 


A 2 indicates that the name is successfully shared with the |/O processor, a 1 
indicates that a value other than 1 was used as the left argument for the 
OSVO function, and a O indicates the shared variable offer failed. When a 1 is 
the result, the variable name is not established as a shared variable. When a O 
is the result, an error message is also displayed (see Appendix F). 


Note: Using the DSVO function without a left argument returns an explicit 
result of 2 or O for each name specified in the right argument. A 2 indicates 
that the name is shared with the 5110 I/O processor, and a O indicates that 
the name is not a shared variable. 


SURROGATE NAMES 
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‘When offering variable names to be shared, you can establish surrogate names 


by specifying two variable names in the character vector or in each row of the 
character matrix. The first name is the surrogate, and the second name is the 
variable to be shared. 


For example: 


CTL is the variable name to be shared, and C is the surrogate. 


NAMES#2 Se'C CTLD DAT! 


NAMES 
C CTL ~+—~CTL and DAT are the variable names to be 
D DAT shared, and C and D are the surrogates. 

1 OSVO NAMES 
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An explicit result is returned for the shared variable names only. 


Once a surrogate name is established, the surrogate name must be used in 
place of the shared variable name during input/output operations. 
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SPECIFYING THE OPERATION TO BE PERFORMED 


Once the shared variables are established, the next step is to specify the 
operation to be performed. These operations consist of: 


* Sequential access to tape or diskette files 
¢ Direct access to diskette files 

+ Direct access to the display screen 

« Sending data to the printer 


After the operation is specified, the |/O processor assigns a return code to the 
shared variable that specified the operation. A On or 22 n return code 
indicates that the operation was specified successfully, and any other return 
code indicates that specifying the operation failed. (See Return Codes later in 
this chapter.) How to specify the input/output operations is discussed next in 
this chapter. 


Note: If a variable has a value when the name is offered to be shared, the 
5110 establishes the name as a shared variable and then attempts to specify 
the operation to be performed using the value already assigned to the shared 
variable. If the data assigned to the shared variable is not valid for specifying 
an operation to be performed, an error message is displayed and the 
appropriate return code is assigned to the shared variable. To prevent this 
error condition, you must make sure that the data assigned to the variable is 
valid for specifying the operation to be performed or expunge (DEX) the name 
before the shared variable offer is made. 


Sequential Access to Tape or Diskette Files 
When you are creating, adding data to, or reading a sequential access data file, 
you must use a single shared variable to access the file. When using tape, you 
can have only one open file on the tape at a time. An open file is a data file 
that is currently being used for input/output operations. When using diskette, 
you can have up to 12 open files at a time (using one shared variable for each 


file). 


The first data assigned to the shared variable must be a character vector that 
specifies one of the following operations: 


« Create a new sequential access data file. 
+ Add data to an existing sequential access data file. 


« Read data from a sequential access data file. 
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OUT, 


To specify one of these operations, the character vector must be in one of the 
following formats (enclosed in single quotes): 


A<'‘OUT device/file number 1!D=(file 1D) [MSG=OFF] [rvee-A] : 


| 
A<‘ADD  [device/file number] [ID=(file 1D)] [MSG=OFF]’ 
A<'IN [device/file number] [ID=(file 1D)] [MSG=OFF]’ 


There must be at least one blank between parameters. Following is a 
description of each parameter. 

ADD, or IN 

This first parameter specifies whether the data is to be written to a new 
sequential access file (OUT), written to an existing sequential access file 
following the last record in the data file (ADD), or read from an existing 
sequential access file (IN). 


device/file number 


This parameter specifies the appropriate diskette drive or tape unit and file 
number. For example: 


11003 
File Number 3 


Diskette Drive 1 


If fewer than four digits are used, the default device is assumed (see Chapter 


2), and this parameter represents only the file number. This parameter is 
optional for diskette files only. See Name Processing in Chapter 2 for more 
information on specifying the device/file number for diskette files. 


ID = (file ID) 


This parameter specifies the file identification (the name is enclosed in 
parenthesis) and is used as follows: 


« When a new data file (OUT operation) is created, the name is put in the file 


ID field of the file header (see The )LIB Command in Chapter 3). If this 


parameter is not specified for tape operations, the file ID defaults to DATA. 


This parameter must be specified for diskette operations. 


It is a good practice to give the data files meaningful names; for example, a 


file that contains sales data could be named sales—iD=(SALES). 


Notes: 


1. See Variable and File Names and Name Processing in Chapter 2 for more 
information on specifying the file ID. 

2. For an OUT operation to an existing data file (writing new data over the 
existing data), the file ID specified must match the existing file ID for the 
data file or the DROP command must be used to drop the data file (see 
Chapter 3). 
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e« When you are adding to or reading from an existing data file (ADD or IN 
operations), the file ID, if specified, is compared to the file ID in the file 
header; the operations cannot be performed if these file IDs do not match. 


MSG = OFF 


This parameter is optional. When this parameter is specified, no error message 
is displayed for nonzero return codes (see Return Codes later in this chapter), 
but the return code is still assigned to the shared variable. 


TYPE=Aorl 


This parameter is specified only when you are creating a new data file (OUT 
operations). This parameter specifies the type of file and data format to be 
used for writing data to a sequential access file: 


e When TYPE=A is specified, the APL internal data format is used (file type 
O08-see The )LIB Command); that is, the data is written to the data file in the 
same format it has in the active workspace. 


Note: TYPE=A is the default if this parameter is not specifed. 


» When TYPE=I is specified, the general exchange data format is used (file 
type 02). When the general exchange data format is used, only character 
scalars and vectors can be assigned to the shared variable. Therefore, 
before you store numeric data or arrays on data files using the exchange 
data format, you must first use the format (¢) function to change the data 
to a character scalar or vector. This data file can also be used as a BASIC 
language source file. When you are adding to or reading from a data file (IN 
and ADD operations), the data format is determined by the existing data file 
type. 


Direct Access to Diskette Files 


When you are creating or adding data to a direct-access diskette file, you use 
a single shared variable to sequentially write the records to the file. When you 
are reading from or writing to an existing direct-access data file, you use a pair 
of shared variables to read or write specified records. In this case, the shared 
variable name with the CTL prefix must be used to specify the operation. You 
can have from 6 to 12 open diskette data files at one time. The number of 
open diskette files allowed depends on how many of the files are existing 
direct access files, because a pair of shared variables is required to access 
these files. 


The first data assigned to the shared variable must be a character vector that 
specifies one of the following operations: 


« Create a new direct access data file. 
- Add data to an existing direct access file. 
» Read data from a direct access data file. 


« Update (read from and write to) a direct access data file. 
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To specify one of these operations, the character vector must be in one of the 
following formats (enclosed in single quotes): 


2 ae 


. 


A<‘OUTF device/file number ID=(file ID) [MSG=OFF] TYPE= of 


2c 


A<‘ADD [device/file number] [!D=(file 1D)] [MSG=OFF]’ 

CTL<INR_ [device/file number] [!ID=(file!1D)] [MSG=OFF] [TYPE=N]’ 
CTL<«‘IOR [device/file number] [ID=(file1D)] [MSG=OFF] [TYPE=N] ’ 
CTL<‘IORH [device/file number] [ID=(file !1D)] [MSG=OFF] [TYPE=N]’ 


There must be at least one blank between parameters. Following is a 
description of each parameter. 
OUTF, ADD, INR, IOR, [ORH 
This first parameter specifies whether the data is to be: 
« Written to a new direct access file (OUTF) 


« Added to an existing direct access file after the last record in the data file 
(ADD) 


e Read only from a direct access file (INR) 

« Read from and/or written to a direct access file (IOR and |ORH) 

The results of an IOR and IORH operation are the same. When you specify 
IORH, an update operation (read and write) is performed faster than if you had 
specified |OR. However, the IORH operation requires more storage in the 
active workspace than does the IOR operation. 

Note: When INR, IOR, or IORH operations are specified, a 0 n or 22 n return 
code indicates that the operation was successfully specified. The second 
element of the return code (n) indicates the number of records in the data file. 


device/file number 


This parameter specifies the appropriate diskette drive and file number. For 
example: 


11003 
File Number 3 
Diskette Drive 1 


If fewer than four digits are used, the default device is assumed (see 
Chapter 2), and this parameter represents only the file number. 


This parameter is optional for diskette only. See Name Processing in Chapter 2 
for more information on specifying the device/file number for diskette files. 
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ID = (file ID) 


This parameter specifies the file identification (the name is enclosed in 
parentheses) and is used as follows: 


e When a new data file (OUTF operation) is created, the name is put in the 
file ID field of the file header (see The )LIB Command in Chapter 3). This 
parameter must be specified for OUTF operations. 


It is a good practice to give the data files meaningful names; for example, a 
file that contains sales data could be named sales—ID = (SALES). 


Notes: 

1. See Variable and File Names and Name Processing in Chapter 2 for more 
information on specifying the file ID. 

2. For an OUTF operation to an existing data file (writing new data over the 
existing data), the file 1D specified must match the existing file 1D for the 
data file or the JDROP command must be used to drop the data file (see 
Chapter 3). 


e When you are adding to (ADD operations) or reading from (INR, |OR, |ORH 
operations) an existing data file, the file ID, if specified, is compared to the 
file ID in the file header; the operations cannot be performed if these file 
IDs do not match. 


MSG = OFF 


This parameter is optional. When this parameter is specified, no error message 
is displayed for nonzero return codes (see Return Codes later in this chapter). 
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TYPE =A, I, U, or M 


This parameter is specified only when you are creating a new direct access 
data file (OUTF operations). This parameter specifies the type of file and data 
format to be used for writing data to a direct access file: 


« When TYPE=A is specified, the APL internal data format is used (file type 
10—see The )LIB Command in Chapter 3); that is, the data is written to the 
data file in the same format it has in the active workspace. The first record 
written to the data file determines the shape (@ DATA) and representation 
that the remaining records must have when these records are written to the 
data file. Each record written to the data file must have the same shape 
and internal representation because if more than one record at a time is to 
be read from the file, the records are laminated together (see Update (Read 
and Write) a Direct Access Data File (IOR and IORH) later in this chapter). 
Following are the classifications for data internal representation: 

— Character 

— Numeric binary (all zeros and ones) 

— Numeric fixed point (all integers in the range -2°' to 23'-1 
— Numeric floating point (all other values) 


Data can be converted from one internal representation to another (by APL 
built-in functions) as follows: 


CHARACTER<% NUMERIC 
BINARY+1ANUMERIC 


This numeric data must be zeros and ones; 


FIXED«+L NUMERIC however, the zeros and ones might be 
FLOAT<NUMERIC + 0.0 fixed-point or floating-point internal 
NUMERIC<2CHARACTER representation. 


This numeric data must be in the 
range -2°! to 29! -1. 


Note: TYPE=A is the default if this parameter is not specified. 


» When TYPE=I is specified, the exchange data format is used (file type 09). 
When the exchange data format is used, only character scalars or vectors 
can be assigned to the shared variable. Therefore, when you are storing 
numeric data on data files using the exchange data format, you must first 
use the format (#) function to change the data to a character scalar or 
vector. The first record written to the data file determines the shape 
(9 DATA) that the remaining records must have when the records are written 
to the data file. Each record written to the data file must have the same 
shape because if more than one record at a time is to be read from the file, 
the records are laminated together (see Update (Read and Write) a Direct 
Access Data File (IOR and IORH) later in this chapter). The data file can also 
be used as a BASIC language source file. 
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« When TYPE=U is specified, the data assigned to the shared variable can 
only be character scalars or vectors. The data is unblocked and unspanned 
as it is written to the data file (file type O09 or BY); that is, each record starts 
on a sector boundary, and a record cannot exceed one sector. Therefore, 
each record must be equal to or Jess than one sector. 


Note: The file type B9 is the basis for general exchange with other 
products. The 5110 assigns the file type B9 to a data file when: 


— TYPE=U is specified when you are creating the data file. 

— The file name is a simple name; that is, the file name cannot exceed 8 
alphameric characters. 

— The records in the file are not greater than 128 characters. 

— The diskette sector size is 128 or 256 bytes. 


Also, you can read TYPE=U (file types 09 and BY) data files sequentially 
(see IN Operations in this chapter) using one shared variable. 


e When TYPE=M is specified, the APL internal.data format is used (file type 
15); that is, the data is written to the data file in the same format it has in 
the active workspace. The first record written to the file determines how 
much file storage is allocated for each additional record. For example, if the 
first record written to the file uses 100 bytes of file storage, each additional 
record written to the file is allocated 100 bytes of file storage (see Storage 
Requirements in Chapter 2 for information on how many bytes of storage 
are required for each data type). For TYPE=M data files, the records do not 
have to be the same shape or representation; therefore, only one record at a 
time can be read from a TYPE=M data file. 


When you are adding records to or updating (reading and writing) a data file 
(ADD, IOR, |ORH, and INR operations), the data format is determined by the 
existing data file type. 


TYPE =N 


This parameter is optional and can be specified only when you are reading 
from or writing to an existing diskette file (IOR, IORH, and INR operations). 
When TYPEEN is specified, all attributes of the file are ignored and data is not 
translated from APL internal code to EBCDIC during output operations, or from 
EBCDIC to APL internal code during input operations. 


When TYPEEN is specified, the system treats each sector in the file as one 
individual record. For example, for a 10K data file on a 512-byte-per-sector 
diskette, there would be 20 records in the file. Also, when TYPE=N is 
specified, only character scalars or vectors can be assigned to the shared 
variable. 


Note: When TYPEEN is specified, the file header can be read (but not written) 
if you specify record number -1. (For information on specifying record 
numbers, see Direct Access (OUTF, ADD, INR, IOR, IORH, and DISPLAY) in this 
chapter.) The file header is always a 128-byte record. 
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Direct Access to the Display Screen 
When you are reading data from or writing data to the display screen, 
specified records are read or written using a pair of shared variables. The 
shared variable name with the CTL prefix is used to specify the operation. The 
first data assigned to the shared variable must be a character vector in the 
following format (enclosed in single quotes): 


CTL<‘DISPLAY [MSG=OFF]’ 


There must be at least one blank between the parameters. Following is a 
description of each parameter. 


DISPLAY 


This first parameter specifies that the pair of shared variables are to be used to 
read data from and/or write data to the display screen. 


MSG = OFF 


This parameter is optional. When this parameter is specified, no error message 
is displayed for nonzero return codes (see Return Codes later in this chapter). 


Send Data to the Printer 


The first data assigned to the shared variable must be a character vector in the 
following format (enclosed in single quotes): 


A<’PRT [MSG=OFF]’ A can be any shared variable. 


There must be at least one blank between the parameters. Following is a 
description of each parameter. 


PRT 


This first parameter specifies that the shared variable is to be used to send 
data to the printer. 


MSG = OFF 


This parameter is optional. When this parameter is specified, no error message 
is displayed for nonzero return codes (see Return Codes later in this chapter). 
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INPUT/OUTPUT OPERATIONS 


After the input/output operation is specified, the actual read and/or write 
operations can be performed. 


Sequential Access Operations 


When a shared variable is used to sepcify a sequential access input or output 
operation, that shared variable is used to transfer the data. 


Writing Data to a Data File (OUT and ADD) 


Each time data is assigned to the shared variable, the data is written to the 
data file and the |/O processor assigns a return code to the shared variable. A 
O O return indicates that the data was written to the data file successfully, and 
a nonzero return code indicates that the operation failed. See Return Codes in 
this chapter for a description of each return code. 


For OUT operations to an existing data file (writing new data over the existing 
data), all the previous data in the data file can no longer be accessed. 


Reading Data from a Data File (IN) 


Each time the shared variable is referenced in the active workspace, the I/O 
processor assigns a new record to the shared variable. The data is read from 
the data file and assigned to the shared variable in the same sequence as the 
data was previously written to the data file. 


Because a new record is assigned to the shared variable each time the shared 
variable is referenced, no return code is assigned to the shared variable after 
each IN operation. An empty vector is returned to indicate an end-of-file or 
an error condition, and the proper return code is then assigned to the shared 
variable. 


Note: Unpredictable results occur if DAV[ 157] (hex 15) or DAV[245] (hex 1E) 


characters are written to and then read from a TYPE=I (file type 2) data file. 
These characters are special record delimiters for the 5110. 
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Direct Access Operations 


Creating a Direct Access Data File (OUTF and ADD) 


When a shared variable is used to specify an OUTF operation, or an ADD 
operation to an existing direct access file, that shared variable is then used to 
write data to the data file. Each time data is assigned to the shared variable, 
the data is sequentially written to the data file and the |/O processor assigns a 
return code to the share variable. A O O return code indicates that the data 
was written to the data file successfully, and a nonzero return code indicates 
that the operation failed. See Return Codes in this chapter for a description of 
each return code. 


For an OUTF operation to an existing data file (writing new data over the 
existing data), any existing data following the new data cannot be used again. 


Updating (Read and Write) a Direct Access File (IOR and |ORH) 


To read from and write to a direct access data file requires a pair of shared 
variables. One of the shared variable names must have the prefix CTL, and the 
other name must have the prefix DAT. After the prefix, the next 15 characters 
in each name must be identical, if specified. For example: 


CTLANAME 


DATANAME 


The shared variable name with the CTL prefix is used to send control 
information to the |/O processor. Also, the 1/O processor assigns the return 
codes to this shared variable. The shared variable with the prefix DAT is used 
to send data to or receive data from the data file. 


Note: When updating a direct access file, you cannot add records to the end 
of the file. Instead, you must do an ADD operation. 


The control information assigned to the shared variable with the CTL prefix 
must be integers in a two- or three-element vector as follows: 


0 
CTL<1 starting record number [number of records] 
2 


Where: 


¢ The first element specifies to read from (0), write to (1), or search by key (2) 
the data file. 


e The second element specifies the starting record number to read, write, or 
search by key. For direct access data files, the first record in the file is 
always number O. Therefore, if record number 1 is specified, the operation 
starts with the second record in the data file. 


¢« The third element is optional. This element specifies the number of records 
to read, write, or search by key. If this element is not specified, one record 
is assumed. 


Reading records, writing records, and search by key procedures are discussed 
next. 
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Reading Records 


When the control shared variable specifies that records are to be read, the I/O 
processor assigns the specified records to the shared variable name with the 
DAT prefix. If more than one record is read, the records are laminated along a 
new first dimension before they are assigned to the DAT shared variable. For 
example, assume that the characters A, B, and C are the first three records in 
the file: 


CTX & OQ @ % --— Read three records, starting with the first record in 
7TLX 


CTL the file. 
0 t= The |/0 processor assigns the return code to the 
PviIaAyTx CTL shared variable. 
x | 
tia TX -——-—— Find the shape of the data assigned to the DAT 
A shared variable. 
i 
(7 The new first dimension. This value also 
HATXE 1; 3 represents the number of records read. 
rs) 
NATXO2; 3 You can specify each individual record by indexing 
B the new dimension. 
NATXUS 5 3 


Once the data read from the data file is assigned to the DAT shared variable, 
the shared variable can be used like any other variable. That is, the DAT 
shared variable retains its value until more data is read from the data file or 
you assign a new value to the DAT shared variable. For example: 


OT LxeO 1 od wo Read the second record in the file. 
TL X 
0 ae retains this value until another record 
' LAT X is read or you assign a new value to DATX. 
CTLXeG Rd Read the third record 
CTLX ee 
00 an DATX now has this value. 
ATX . 


HATXe SA oe Assign a new value to DATX. 


P DAT now has this value. 


Writing Records 


When the CTL shared variable specifies that records are to be written, the I|/O 
processor writes the current value of the DAT shared variable to the data file. 
If more than one record is specified to be written to the data file, the records 
must be joined along a new first dimension before they are assigned to the 
DAT shared variable. For example, assume you want to write the three records 
A, B, and C to a data file: 


QATX¢S 1 p' ARC’ 


DATX Join the records along a new first dimension. 
A 
kk 
C; 
CTLXeL 0 % Write the three records currently assigned to the 
Thx DAT shared variable to the data file. 
0 0 Sa ae 
Now the first three records in the data file are A, 
B, and C. 


To update a direct access data file, you can read the record(s) from the data 
file, modify the record(s), and then write the modified record(s) back to the 
data file. For example: 


CTLAtO 0 3 


CTL X 
o 9 
ATX 
3) 
gfe Thee first three records in the data file. 
(’ 
QATXEL 2 35 16° EF * Modify the three records read from 
NAT X the data file. 
yi 
i 
JF 
OTe lL OS Write the modified records back to the 
TL data file at a specified location. 


0 Q a ee 
Now, the first three records in the data 


file are D, E, and F. 
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Search by Key 


Search by key can be used with direct access interchange, general interchange, 
unblocked/unspanned, and APL internal format data files. When the CTL 
shared variable specifies a search by key, the key value presently assigned to 
the DAT shared variable is used to search the data file. The key must be: 


« The same representation as the data in the data file (character, binary, fixed 
point, or floating point) 


e Less than or equal to 255 bytes for 256-byte-per-sector diskettes 
e Less than or equal to 128 bytes for 128-byte-per-sector diskettes 


e Less than or equal to the record size for unblocked/unspanned format data 
files (TYPE=U) 


For a search by key, the records in the data file cannot span any sector 
boundaries, and the records should be sorted in ascending sequence. That is, 
one sector can contain multiple records; however, the records cannot span a 
sector boundary. 


The key is compared with the equivalent number of beginning bytes in each 
sector. The search starts with the sector containing the first record specified 
and continues through the sector containing the last record specified 
(determined by the number of records specified). The search is completed 
when: 


« The key is equal to the equivalent number of beginning bytes in the sector. 
In this case, the records in the sector are assigned to the DAT shared 
variable. 


¢ The key is less than the equivalent number of beginning bytes in the sector. 
In this case, the record(s) from the previous sector are assigned to the DAT 
shared variable. The comparison between the key and the beginning bytes 
of each sector is an unsigned binary comparison (bit by bit). Therefore, the 
following collating sequences are implied: 


— For interchange, general interchange, and unblocked/unspanned format 
data files, the EBCDIC character sequence. 

— For character data in APL internal format files, the atomic vector (DAV) 
character sequence. 

— For binary data, unsigned integer sequence. 

— For numeric data, an unsigned integer sequence. That is, for fixed point 
data, the negative values follow the positive values. For floating point 
data, the negative values are in reverse order and follow the positive 
values. 


« The EOD address is encountered as the specified records are being 
searched. In this case, the record(s) in the last sector of the file are 
assigned to the shared variable. 


« All of the specified records are searched without one of the previous 
conditions occurring. In this case, the search is unsuccessful, and a 1 029 
return code is assigned to the CTL shared variable (see Return Codes later in 
this chapter). 


Notes: 

1. If the key is equal to the beginning bytes of a sector, but the beginning 
bytes in a previous sector searched are greater than the key, the sector 
containing the bytes equal to the key will not be reached. 

2. Characters records should be sorted in ascending sequence for search by 
key operations. 


If the search is successful and the sector contains more than one record, the 
records are laminated (joined) together along a new first dimension and 
assigned to the DAT shared variable. Therefore, the first dimension of the DAT 
shared variable represents the number of records read and assigned to DAT. 


After the search is successfully completed, the return code assigned to the 
CTL shared variable is O n, where n represents the record number of the first 
record assigned to the DAT shared variable. 


Reading a Direct Access Data File (INR) 


Reading the data from a direct access file using an INR operation requires a 
pair of shared variables. 


Note: Generally, an INR operation is specified when the data is to be read 
from and not written to the file. This prevents data from accidently being 
written to the data file. 


The control information assigned to the shared variable with the CTL prefix 
must be integers in a two- or three-element vector as follows: 


CTL<) starting record number [number of records] 


Where: 


« The first element must be O (specifying that data is to be read from the file) 
or 2 (specifying a search by key operation). 


« The second element specifies the starting record number. For direct access 
data files, the first record in the file is always number O. Therefore, if record 
number 3 is specified, the operation starts with the fourth record in the data 
file. 


« The third element is optional. This element specifies the number of records. 
If this element is not specified, one record is assumed. 


See Reading Records and Search by Key earlier in this chapter for a description 
of how records are read from a data file or data files are searched by key, 
respectively. 
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Reading from and Writing to the Display Screen (DISPLAY) 


To read from and write to the display screen requires a pair of shared 
variables. One of the shared variable names must have the prefix CTL, and the 
other name must have the prefix DAT. After the prefix, the next 15 characters 
in each name must be identical, if specified. For example: 


CTLDISPLAY 
DATDISPLAY 


The shared variable name with the prefix CTL is used to send control 
information to the !/O processor. Also, the |1/O processor assigns the return 
code to this shared variable. The shared variable name with the prefix DAT is 
used to send data to or receive data from the display screen. 


The control information assigned to the shared variable with the CTL prefix 
must be integers in a two- or three-element vector as follows: 


CTLes starting character number [number of characters] 


Where: 


e The first element specifies that data is to be read from (0) or written to (1) 
the display screen. 


« The second element specifies the starting character number to read or write. 
The characters are numbered as follows: 


Line 


15 
14 
13 
12 


Om NWOHAHD~ CO O 


e The third element is optional. This element specifies the number of 
consecutive characters to read or write. If this element is not specified, only 
one character is assumed. If the specified number of characters plus the 
starting character number exceeds the value 1024 (the total number of 
characters that fit on the display screen), a 15 O return code is assigned to 
the CTL shared variable. 
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Reading Records from the Display Screen 


When the CTL shared variable specifies that characters are to be read, the 
cursor appears on the display screen at the character position specified by the 
starting record number. You can then modify the information on the display 
screen for the specified number of characters. For example, pressing ATTN 
erases any data from the cursor position to the last specified character. Now, 
when the EXECUTE key is pressed, the specified characters are read from the 
display screen and assigned to the DAT shared variable as a character vector. 


For example, assume the first 3 characters on the display screen are A, B, and 
C: 


CYLOISPLAY¢eO @ 3 


——Read 3 characters. 
Start with the first character. 
Once the previous statement is executed, the cursor (flashing character) is at 
the first character position on the display screen. Now, if you enter the 3 


characters DEF and press EXECUTE: 


NATOISPLAY 


DE is aemerm aie 
CTLUISPLAY 


variable. 


Once the character vector read from the display screen is assigned to the DAT 


shared variable, the shared variable can be used like any other variable in the’ 
active workspace. 


Note: When you are reading data from the display screen using a loop, you 
should program an escape from the !oop in your user-defined function. For 
example: 


LOOP: CTLOYSPLAYe0 0 20 
SCOFLTCTLOTSPLAY I /0 

3eCA/ OUT = StoATOISPLAY) ZOUT 
Xe xX CLIVATOLSPLAY 

LOOP 


The specified characters currently on the display 


0 0 a ee read and assigned to the DAT shared variable. 


The return code is assigned to the CTL shared 


our: Branch out of the loop if the first 3 characters 


read are OUT. 


This is necessary because you cannot interrupt reading data from the display 
screen using the ATTN key. 
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Writing Records to the Display Screen 


When the CTL shared variable specifies that records are to be written, the |/O 
processor writes the current value of the DAT shared variable to the Olsp lay 
screen. For example: 


QATUISPLAYe ‘NEW 
CTLOISPLAY¢1 0 4——— Write the three records N, E, and W to the first 


CTLOLSPLAY three positions of the display screen. 
0 0 
NE The return code is assigned to the CTL shared 
variable. 


If the DAT shared variable contains more data than the CTL shared variable 
specifies to be written to the display screen, only the specified number of 
records are written to the display screen, starting with the first record of the 
character vector assigned to the DAT shared variable. If the DAT shared 
variable does not contain as many characters as specified by the CTL shared 
variable, the error messages 10 STATUS: INVALID DAT and INTERRUPT are 
displayed (unless MSG=OFF is specified). 


Sending Data to the Printer (PRT) 


When a shared variable is used to specify that data is to be sent to the printer, 
data (character scalar or vectors) assigned to that shared variable is sent to the 
printer. Then the I/O processor assigns a return code to the shared variable. 
AO 0 return code indicates that the data was printed successfully, and a 
nonzero return code indicates that the print operation failed. See Return Codes 
later in this chapter for a description of each return code. 


Note: The )OUTSEL OFF command is automatically issued by the system 
during PRT operations. The )OUTSEL option returns to its previous eorune 
after the PRT operation is terminated. 


TERMINATING THE OPERATION 


When you no longer need a shared variable (or pair of shared variables) for a 
specified operation, you can terminate the operation by: 


e Assigning an empty vector to the shared variable 


« Completing execution of a user-defined function in which the shared 
variable is made local to that function 


« Using the DEX function or )ERASE command 


« Using the USVR function 


Assigning an Empty Vector to the Shared Variable 


For sequential access operations (IN, OUT, and ADD), the I/O processor 
terminates the operation when you assign an empty vector to the shared 
variable. For output operations, the file header is updated with information 
about the file (see The )LIB Command in Chapter 3). For input operations, the 
operation is also terminated when an end-of-file empty vector is read from the 
data file or an error occurs due to the device (and the proper return code is 
assigned to the shared variable). 


CAUTION 

For OUT, OUTF, and ADD operations, if the media is removed from the 
system before the operation is terminated, the data file will be unusable. Any 
subsequent attempt to read from the data file will give unpredictable results. 


When creating a direct access data file (OUTF and ADD operations), the |/O 
processor terminates the operation and updates the file header with the EOD 
address when you assign an empty vector to the shared variable. 


For direct access operations to read from and write to a data file or the display 
screen (IOR, IORH, INR, and DISPLAY), the |/O processor terminates the 
operation when you assign an empty vector to the CTL shared variable. 


For printer operations (PRT), the |/O processor terminates the operation when 
you assign an empty vector to the shared variable. 


The |/O processor assigns a return code to the shared variable after the 
operation is terminated. The O O return code indicates that the operation was 
terminated successfully. See Return Codes later in this chapter for a description 
of each return code. 


After an empty vector is used to terminate the operation, the shared variables 
can be used for specifying and performing other input/output operations. 
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Making the Shared Variable Local to a User-Defined Function 


If a shared variable name is local to a user-defined function, the input/output 
operation is automatically terminated when the user-defined function 
completes execution. See Assigning an Empty Vector to the Shared Variable for 
a description of what happens when the operation is terminated. In this case, 
there is no return code assigned to the shared variable. 


Using the DEX Function or JERASE Command 


If the shared variable is expunged (DIEX) or erased ()ERASED), the 
input/output operation is automatically terminated. See Assigning an Empty 
Vector to the Shared Variable for a description of what happens when the 
operation is terminated. In this case, there is no return code assigned to the 
shared variable. 


Using the OSVR Function 


When you no longer need a shared variable for input/output operations, you 
should use the JSVR system function to retract the shared variable offer. If 
the shared variable offer is retracted before you have terminated the 
input/output operation, the system will automatically terminate the operation. 
See Assigning an Empty Vector to the Shared Variable for a description of what 
happens when the operation is terminated. In this case, there is no return code 
to the share variable. 


RETRACTING THE SHARED VARIABLE OFFER 


To retract the offer to share a variable between the |/O processor and the 
active workspace, the DSVR function is used. This function is monadic 
(requires one argument); the argument is character data that specifies the 
shared variable name(s) being retracted. For example: 


SVR NAME * 


If more than one name is used in the argument of the LISVR function, the 
names must be in a character matrix with each row representing one name. 
For example: 


SVR 4 Le  ABCT 


or Each row represents a separate variable name. 


NAMES¢H Le ARC 
SVR NAMES 


The explicit result of the OSVR system function is a 2 or O for each shared 
variable name being retracted as a shared variable. 


For example: 


SVR 4 Le ABCT 


cy ae De AS 
fA YOu ots 


A 2 indicates that the name is successfully retracted as a shared variable with 
the I/O processor. A 0 indicates that the name is not successfully retracted as 
a shared variable. Normally, if a shared variable offer cannot be retracted 
successfully, it was never properly established as a shared variable. 


Retracting the shared variable offer does not erase the value assigned to the 


variable. That is, the variable still has a value after the shared variable offer is 
retracted, until the variable is expunged or erased (LJIEX or )ERASE). 
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RETURN CODES 


The |/O processor assigns a return code to the shared variable after each of 
the following operations: 


¢« Specifying the operation to be performed 

e Writing records to a sequential access file 

e Writing records to and reading records from a direct access file 
e Writing records to and reading records from the display screen 
e Sending data to the printer 


¢« Terminating the operation by assigning an empty vector to the shared 
variable 


e Reading the last record of a sequential access file 
e Reading a sequential access file when an input error occurs 


The return code indicates whether or not the operation was successful. If the 
return is nonzero and MSG=OFF is not specified, in most cases an error 
message is also displayed. You can check the return code by referencing the 
shared variable once after the operation is complete. When the shared variable 
is referenced more than once to check a return code, the error messages !O 
STATUS: INVALID OPERATION and INTERRUPT are generated. Therefore, if 
you need to check the return code more than once, you must first assign the 
return code to another variable. For example: 


m4 (TL, In this example, CTL is a shared variable that has 
rs been assigned a O O return code. 


Oe ih The shared variable cannot be referenced 
LO STATUS INVALID OPERATION more than once for a return code. 
INTERELIPT 


“y= 


L, | Ls 


Execution of a user-defined function does not stop when a nonzero return 
code is assigned to the shared variable. Therefore, the user-defined function 
should check the return code that was assigned to the shared variable to make 
sure that each operation is successful. For example: 

LF OATRe OUTF Lidgodd Te CNAME) TYPE=U" 

fet] SCOF LT XETATX ME RROR 

Pié dd ERROR: (SPECIFYING THE OPERATION FATLED--THE RETURN CODE IS: 

aoe a A 


es ae ae Si 2 | 


eve 


Following is a description and/or user’s response for each return code and 
error message: 


Code Error Message 
ON 
1 eee 
20 IO STATUS: INVALID FILE 
30 10 STATUS: INVALID DEVICE or 

IO STATUS: INVALID DEVICE NUMBER 
40 IO STATUS: INVALID FILE NUMBER 
50 10 STATUS: NOT WITH OPEN FILE 
60 10 STATUS: INVALID PARAMETER 
70 IO STATUS: WS FULL 
80 10 STATUS: DEVICE NOT OPEN 


Description and/or User's Response 


Operation successful. When you are specifying 
direct access read and write operations (IOR, 
IORH, and INR), the second element is the 
number of records in the data file. When you 
are doing search by key operations, the second 
element is the number of the first record read. 
Otherwise, the second element is zero. 


Device error; the second element (eee) is the 
error code (see ERROR eee ddd in Appendix F). 


The specified file cannot be used for 
input/output operations. 


Specify the operation again, using the correct 
device number. 


Specify the operation again, using a valid file 
number. | 


The specified file, device, or corresponding DAT 
shared variable is already being used for 
input/output operations; the current operation 
must be terminated before a new operation can 
be specified. 


The parameters required to specify the 
operation were entered incorrectly; specify the 
operation again, correcting any keying errors. 


There is not enough space in the active 
workspace for data items and buffers 
associated with the |/O operation. Use the 
JERASE command or the LIEX function to erase 
any unwanted objects; then specify the 
operation to be performed again. 


An attempt was made to use a shared variable, 
and an |/O operation has not been specified. 
Specify the 1/O operation to be performed, or 
retract the shared variable if you want to use it 
as an ordinary variable. 


An empty vector was read from the data file, 
but the empty vector is not the end-of-file 
empty vector. This return code is only a 
warning. 
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Code Error Message 

10 O 1O STATUS: EXCEEDED MAXIMUM RECORD LENGTH 
11 0 10 STATUS: INVALID DATA TYPE 

12 0 10 STATUS: FILE NOT FOUND 

13 0 10 STATUS: FILE NOT UNIQUE 

14 0 10 STATUS: WRITE PROTECT 

15 0 10 STATUS: CTL DOMAIN ERROR 

16 0 10 STATUS: INVALID DAT 


18 0 10 STATUS: NO DAT 
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Description and/or User's Response 


The error was probably caused by the tape 
being removed before the file was closed. The 
remaining data in the file cannot be read. 


The wrong type or shape of data was used; for 
example, noncharacter data was sent to an 
exchange file, or noncharacter data was used as 


_the parameters when you specified the 


operation to be performed. 


The diskette files were searched by file name, 
but the file name was not found. Specify the 
operation again, using the correct file name, or 
insert the proper diskette. 


The diskette files on all the diskette drives were 
searched by file name, and there is more than 
one file with that name. Specify the operation 
again, using the device/file number parameter. 


The data file is write-protected. If you want to 
write on the file, use the JPROTECT command 
to remove the write-protect indicator. 


invalid control information was assigned to the 
CTL shared variable; for example, a record 
number greater than the number of records in 
the data file was specifed. 


Note: For a TYPE=M (file type 15), anytime you 
specify the number of records this return code 
is generated. instead, you must let the 5110 
use the default value (1). 


The data assigned to the DAT shared variable 
cannot be written to the data file. For example, 
the data has the wrong shape and/or 
representation for the data file. 


The DAT shared variable is not established as a 
shared variable before the CTL shared variable 
is used to specify a direct access input/output 
operation. 


Code 


22 N 


23 0 


24 0 


Error Message 


10 STATUS: WRONG VOLUME 
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Description and/or User's Response 


The operation is specified successfully, and the 
second element is the number of records in the 
file. However, the records were written to the 
file such that if the file contains a bad sector, 
that sector is skipped and the record is written 
to the next sector. If there are no bad sectors, 
the file can be read without any problems. If 
there are bad sectors, a 1 44 return code is 
issued if you try to access a bad sector. If the 
file contains a bad sector, you must determine 
the correct record location. For example: 


Record Number 


3 


[rec =a RECORD B | ae RECORD D a ‘Voor File 1 


2 3 


RECORD seal RECORD B | Bad Sector RECORD o[ RECORD ono o| A File 2 


In data file 1, tf you specify to read record 
number 2, RECORD C is read. In data file 2, if 
you specify that record number 2 should be 
read, a 1 44 return code is issued. Instead, you 
must specify record number 3 in order to read 
RECORD C. 


The end of the file was encountered when the 
system was creating a direct access exchange, 
unblocked/unspanned, or internal format data 
file (type 9 or 10). The system automatically 
terminates the operation and updates the file 
header when this return code is issued. 


An attempt was made to read from or write to 
a diskette data file, and the diskette is not on 
the same diskette drive as when the operation 
was specified. Place the diskette containing the 
data file in the same diskette drive as when the 
input/output operation was specified, and try 
the operation again. 
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INPUT/OUTPUT SUMMARY 


Following is a summary and examples of the steps required for input and 
output: 


1. Make a shared variable offer and check the result. 


XMeATSVO 2 4 p' CTLXDATX’ 
bov 28x ERROR 


ERROR: THE SHARED VARTAGBLE OFFER FATLED, ' 


2. Specify the operation to be performed and check the return code. 


Ae ALN L100) TG (SEQUENTIAL? MSG=0FF' 

Xe’ TN 11001 [te (SEQUENTIAL) MSG=OFF ' 

Xe" QOQUTF 21001 Tle COL RECT? MSGeOFF TYPES 
QATMe “ANT L001 The (QTRECT) MSGsOFF' 

CYTLAG INR LLO01 TD (QTRECT) MSGeOQFF TYPE =N' 
CTL’ TOR 21001 Ite COTRECT) MSGeOFF TYPE=N‘ 
CTLXe  TORH 11001 [De (OTRECT) MSG=OFF TYPE=N' 
CTLAXG  TISPLAY MSG2OFF ' 


Xe "OUT 112001 I0=(SEQUENTIAL) MSG=OFF TYPE=T | 
Sequential Access 
Direct Access 


QATXe PRT MSGsQFFS 0 —————————_____—_——__ Printer Output 


SCOFLTIATXI/SERROR? 
° Check Return 
< Code 
ERRORS SPECTFYING THE OPERATION FAILED, ' 


3. Perform the input and output operations, and check the return code after 
each operation. 


CTLX¢) O § Direct access—Read five records, starting with the 
first record. 


CTLX¢d 1 Direct access—Write five records, starting with the 
second record. 


CTLXe2 10 8 Direct access—Search by key five records, starting at 
the sector that contains the eleventh record. 


eS COFTTSVECTLX? /ERRORS 
2 Check 
& Return 
te Code 
ERRORS: I/O OPERATION FAILED, THE RETURN COLE Is: ",79¥ 
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4. Terminate the operation and check the return code. 


CTL Xe 10 
SCOT TCTLXO/ERRORY 


ERRORG: “TERMINATING THE OPERATION FAILED, 
5. Retract the shared variable offer and check the results. 

X¢T]ISVR 2 we  CTLXDATX' 

iv Se xO YE REO RES 


$+ 


a 


ERRORS: "RETRACTING THE SHARED VARTARLE OFFER FATLED, 


Note: Even after the shared variable offer is retracted, the variables still 
have a value. 
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Chapter 8. The 5103 Printer 


The IBM 5103 Printer is available as a feature attachment and has these 
characteristics: 


¢ Bidirectional printing (left to right, then right to left). The 5103 bidirectional 
printing operates as follows: 


The print head moves from the left margin and prints a line. Succeeding 
lines are printed in either direction depending on which end of the new line 
is closest to the current position of the print head. The print head is 
returned to the left margin periodically when printing is not imminent. 


e 132 characters across the print line. 


Note: If the width of the forms is less than 132 characters and the DPW 
system variable (see Chapter 5) is greater than the width of the forms, loss 
of data will occur as the print head leaves the form. 


e Capability of using individual or continuous forms. Maximum number of 
copies is six, but for optimum feeding and stacking, IBM recommends a 
maximum of four parts per form. 


¢ Adjustable forms tractor that allows the use of various width forms. The 
forms can be from 3 to 14.5 inches (76.2 to 368.3 millimeters) wide for 
individual forms and from 3 to 15 inches (76.2 to 381 millimeters) wide for 
continuous forms. 


¢ Print position spacing of 10 characters per inch (25.4 millimeters) and line 
spacing of six lines per inch (25.4 millimeters). 


¢ Stapled forms or continuous card stock cannot be used. 


¢ The character printing rate is 80 or 120 characters per second. The 
throughput in lines per minute is function-dependent. 


e A vernier knob (located on the right side of the printer) that allows for fine 


adjustment of the printing position. This knob should only be used when 
the print head is in its leftmost position. 
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» The forms must meet the following requirements: 


Singlepart 
Cut Forms 


0.0075 inch 
(0.019 cm) 


Maximum Thickness 
Minimum Thickness 0.003 inch 
(0.0076 cm) 


Maximum Width 14.5 inches 


(36.83 cm) 


Minimum Width 6 inches 
(15.24 cm) 


Maximum length 14 inches 
(35.56 cm) 


Minimum length 3 inches 
(7.62 cm) 


Maximum Copies 


Maximum Form Weight 


Maximum Distance 
Between Folds 


Multipart 


Cut Forms 


0.018 inch 


(0.0457 cm) 


0.003 inch 
(0.0076 cm) 


14.5 inches 
(36.83 cm) 


6 inches 
(15.24 cm) 


- 14 inches 


(35.56 cm) 


3 inches 
(7.62 cm) 


4 


Continuous 
Forms 


0.018 inch 
(0.0457 cm) 


0.003 inch 
(0.0076 cm) 


14.87 inches 
(37.76 cm) 


3 inches 
(7.62 cm) 


4 


15 Ib ream 


— (6804 kg) 


14 inches © 
(35.56 cm) 


HOW TO INSERT FORMS 


Continuous Forms 


Form Guide Rack 1. Slide the top cover forward. 


2. Push the print head to the extreme left position. 


Rollers 3 > For singlepart forms, pivot the form guide rack up 


and forward to a vertical position. For multipart 

: forms, leave the forms guide rack in the horizontal 
Print Head - g 
position. 

The diagrams below and to the left show the 
proper forms path for singlepart and multipart 
forms. 


4. Push the paper release lever to the rear to activate 
the friction feed rolls. 


5. Place the forms on the table behind the printer. 


Note: The forms must be positioned behind the 
printer so that the forms feed squarely into the 
printer. 


© 


ae 


Paper Release Lever ; 
6. Thread the paper down, over the rollers, behind 


| 
Printer Cover Paper-Advance Knob the tractors, and behind the platen. 
Vernier Knob 
7. Turn the paper-advance knob to move the paper 
around the platen until you can grasp it with your 
fingers. 


Forms Path for Singlepart Forms 
Forms Guide Rack 


Rollers — bay aes 
i lower position) 


Position these guides at the edge of the paper. 


Platen 


a 


Friction Feed Rolls 
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Tractor Cover and Pins 


rae 


Paper 
Release 
Lever 


Paper-Advance 


Tractor Cover and Pins Knob 
Right Tractor Knobs 
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11. 


12. 


16. 


17. 


18. 


Open both tractor covers. 


Pull the paper release lever forward to disengage 
the friction feed rolls. 


Pull the paper up and place the left margin holes 
over the tractor pins. Be sure the left tractor is in 
its leftmost position. 


Close the left tractor cover. 


Squeeze the two knobs on the right tractor, and 
slide the tractor to align the pins with the right 
margin holes. 


Place the right margin holes over the tractor pins. 
Close the right tractor cover. 


For singlepart forms, pivot the forms guide rack to 
a horizontal position. 


Turn the paper-advance knob to position the form 
for the first line to be printed. The paper should 
exit over the forms guide rack. 


Note: To move the form backward, turn either 
paper-advance knob backward and pull the form 
from behind the printer to keep the form from 
buckling at the print head. 


Close the top cover. 


The plastic guides on the rear of the wire rack 
should be positioned (one on each side of the 
forms) so as to aid in guiding the forms for proper 
feeding. These guides are positioned by sliding 
them back and forth. 


CAUTION 

The switch that senses end of forms is deactivated 
when the friction feed rolls are engaged. Thus, the print 
wires could hit the base platen if no forms are in the 
printer. 


Cut Forms 


tT, Remove the forms tractor by tilting it back and lifting it off. 

2. Move the cut forms guide forward. 

3: Slide the top cover forward. 

4. Push the print head to the extreme left position. 

5. Push the paper release lever to the rear to activate the friction feed rolls. 

6. Place the form in position behind the platen and against the cut forms 
guide. 

wis Turn the paper-advance knob to position the form for the first line to be 
printed. Improve the paper alignment if necessary by using the paper 
release lever. 

8. Close the top cover. 

CAUTION 


The switch that senses end of forms is deactivated when the friction feed rolls 
are engaged. Thus, the print wires could hit the base platen if no forms are in 
the printer. 


Printer Cover 


Cut Forms Guide 


Paper Release Lever 


Paper Advance Knob 
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HOW TO ADJUST THE COPY CONTROL DIAL FOR FORMS THICKNESS 


re) Copy Control Dial 


If you are using singlepart forms, set the copy 
control dial on O. 


if you are using multipart forms and the last sheet 
is not legible, rotate the copy control dial toward 0 
one click at a time to obtain the legibility you 
desire. 


If you are using multipart forms and the ribbon is 
smudging the first sheet, rotate the copy contro! 
dial toward 8 one click at a time until smudging 
stops. 


HOW TO REPLACE A RIBBON (PART NUMBER 1136653) 


Forms Tractor 


XS 
Pec 
LPs 


Printer Cover POWER ON Switch 
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\ 
My \ 
GS 


Turn off power to the printer. 


Tilt the forms tractor back by lifting both sides 
at the front. 


Slide the top cover forward, then lift the front 
edge of the top cover and remove it. 


Ribbon Box Cover 4. Be sure that the print head is to the extreme left. 


Feed Roll 5. Turn the feed roll release knob counterclockwise 
Release Knob until it points to the right. 


Print Head 


6. Open the ribbon box cover. 
7. Put on the gloves supplied with the new ribbon. 


8. Remove the old ribbon fram the guides being 
careful to disengage it from the clip on the print 
head. 


9. Lay the ribbon loop on the top of the ribbon in the 
ribbon box. Pick up the entire ribbon and discard 
it. 


Ribbon Loop 


Disk 


Ribbon Holder 


Print Head 


10. Eject the new ribbon from its holder into the 
ribbon box by pressing on the disk. 


11. Remove the disk from the ribbon and discard the 
disk and the holder. 


12. Hold the coil lightly with one hand and pull about 
10 inches (254 mm) of ribbon from the coil, 


13. Form a loop from the ribbon across the print head. 


Loop 


The 5103 Printer 213 


Upper 


Guide Post Platen Feed Rolls 


Guides 


> — Feed Roll 


Release Knob 


Left 
Guide Post 


Guide Shoe 


Slot Ribbon Box 
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14, Thread the part of the loop nearest the platen 
between the feed rolls and on the inside of the 
upper guide post. 


15. Turn the feed roll release knob clockwise to close 
the feed rolls. 


16. Thread the ribbon between the print head and the 
platen. Be sure the ribbon is under the clip on the 
print head. 


17. Thread the other part of the loop through the slot 
in the bottom of the ribbon box. 


18. Thread the ribbon through the guide shoe and 
around the left guide post. 


19. Insert the horizontal part of the ribbon twist 
(bottom edge first) between the two horizontal 
guides. 


20. Move the print head back and forth across the 
platen to remove the slack from the ribbon. 
Continue moving the print head until you are sure 
that the ribbon feeds properly. Leave the print 
head at the extreme left. 


21. Close the ribbon box cover. 

22. Close the printer cover and turn the power on. 
23. Reposition the form tractor. 

Note: When the printer is left unattended (such as 
during lunch or overnight), make sure the print head is 


to the extreme left. This prevents the ribbon ink from 
bleeding onto the paper. 


HOW TO INSTALL THE 5103 PRINTER STACKER 


A folded-form paper stacker is supplied with 5103 printers. The wire stacker 
hooks onto the back of the printer cover as shown in the drawing. The lower 
wires on the stacker should contact the metal clips on the cover. 


The stacker can be bent if too much weight is applied. Under normal 
conditions, printed forms should not be allowed to accumulate higher than 1 
inch in the stacker. 


Note that, because of the relatively small free-fall distance of the paper as it 
leaves the printer, you may have to manually fold the first two or three sheets 
to get the folding operation started. 
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Appendix A. 5110 APL Character Set and Overstruck Characters 


To form overstruck characters, enter one character, backspace and enter the 
other character or use the applicable CMD/key combinations. The 5110 APL 
character set consists of all the characters represented on the 5110 keyboard 
plus the following overstruck characters: 


Function Character . Keys Used 
Comment A 

Execute 2 

Factorial, combination : 

Format r 

Grade down Y 

Grade up A 

Logarithm ® 

Matrix division GJ 

Nand rN 

Nor Vv 

Protected function Vv 

Quad quote C 

Rotate, reverse fo) 

Transpose & 

Compress / (see note) 
Expand 4 (see note) 
Rotate, reverse e (see note) 


Note: These are variations of the symbols for these functions; they are used 
when the function is acting on the first coordinate of an array. 
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Appendix B. Atomic Vector 


CHARACTER CHARACTER NAME TNQEX C(]LOed) 
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Note: The characters | (QAVE@187), 2 COAVE2199), |! CAVE aN2g), 
* (TAVES48I), and \ (QAVE2517) are similar in appearance to the 
symbols for the APL built-in functions, However, if these 
characters are used as APL built-in functions, a ENTRY ERROR 

ie displayed. 


Atomic Vector 223 


224 


Appendix C. EBCDIC Character Set and Special National Graphics 


The system translates the APL internal code into EBCDIC (extended binary 
coded decimal interchange code) when data is written to tape or diskette. The 
following chart shows the character that is displayed or printed for each 
EBCDIC hexadecimal value: 


Beane eae 


”~ 
—_ 


<a 


EAE Ed 


_ 
Me 


G 
_ 
eae 


~< 


) 
W 


| ~ | x 


For example, The EBCDIC character O has a hex value FO. 
In the previous chart, graphics are assigned to all blank positions (except hex 


40) for maintenance use only. These graphics are incompatible with other 
systems and cannot be used for exchange purposes. 
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Some of the graphics in the previous chart change when a national character 


set, other than EBCDIC, is specified. You can specify other national character 
sets by: 
+ Using the DCC system function (see Chapter 5) 


e Pressing the HOLD key, and then holding down the shift key and pressing: 


1 to select Austria /Germany 9 to select Portugal 

2 to select Belgium O to select International 

3 to select Brazil + to select Spain 

4 to select Denmark / Norway x to select Spanish Speaking 
5 to select Finland/Sweden - to select United Kingdom 
6 to select France + to select French Canadian 
7 to select Italy . to select EBCDIC 


8 to select Japan 


« Having your service representative change the character set that is in effect 
when the power is turned on or RESTART is pressed. In this case, you can 
still select any of the other character sets from the keyboard or a 
user-defined function. 


The following chart shows the hexadecimal value and associated national 
graphics for each unique national character set: 


Country Hex Position 
SA SB SF 6A 79 7B 70 AL CO TO EO 


Austria/Germany 
Belgium 

Brazil 
Denmark/Norway 
Finland/Sweden 
France 

Italy 

Japan 

Portugal 
International 
Spain 

Spanish Speaking 
United Kingdom 
French Canadian 
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Appendix D. 5110 Compatibility with the IBM 5100 


The 5110 APL system differs from the 5100 APL system as follows: 
¢ The following system commands have been added to support the diskette: 


)FILEID )PROTECT 
)FREE )VOLID 


¢ The system commands )PROC, )LINK, )RESUME, and )SORT have been 
added to enhance the system. 


¢ The following system functions and variables have been added to maintain 
syntactic compatibility between the 5110 and APLSV: 


Default Value 


DAI 0000 

ODL 0 

OTs 1990000000 
OT 0 

OUL 1 


* The system variable DCC has been added to enhance the system. 
¢ For system commands that have device/file number and workspace ID 
parameters, only one or the other parameter needs to be specified for 


diskette interface. 


« When shared variables are used, Surrogate names can be specified and 
used. 


* Overlapped printing (one line only) occurs as the 5110 processes data. 
e The EBCDIC character set is used for diskette files. 
« Lowercase characters can be entered from the keyboard. 


+ The OPW value is used during VFUNCTION[O]V. 
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Single or multiple records on diskette direct access data files can be read or 
written when you specify the record number using a shared variable. 


Records on the display screen can be read or written when you specify the 
record number using a shared variable. 


A strong interrupt is caused when you hold down the SHIFT key and press 
the ATTN key. 


References to a shared variable that has not been used to specify an 
operation to be performed causes an INTERRUPT error message. 


If the format function is used with a shared variable during input operations, 
alternate records are not skipped if the input data is already in character 
form. 


File types 2, 7, and 8 can be written on tape by the 5100 and read by the 
5110, and vice versa. 


Only workspaces written to tape with the )SAVE command by the 5100 can 
be loaded or copied into the 5110 active workspace. 5100 continued 
workspaces (file type 6) and 5110 continued workspaces (file type 26) are 
not compatible. 


The 5110 requires 224 bytes more overhead from the user work area than 
did the 5100. Therefore, some programs that executed on the 5100 might 
generate a WS FULL error on the 5110. 


Programs written for 5100 shared variable operations that permit you to 
specify the device/file number and then use the default file name DATA will 
not work for 5110 diskette files. The program must be changed so that you 
must also specify a simple or complex file name. 


Appendix E. 5110 APL Compatibility with IBM APLSV 


The 5110 APL system differs from the IBM APLSV system primarily because 


the 5110 is a single user system with different input/output devices and it has 


display screen output rather than typewriter output. The differences are as 


follows: 


Turning power on signs the user on; therefore, no.sign-on or ID number is 
required. 


The 5110. active workspace is generally smaller than APLSV active 
workspace. It is further limited by the |/O processor and shared variable 
processor, which use it for input/output buffers and work areas. 


The default number of symbols is 125 instead of 256, which increases the 
available workspace for most users. 


The library number that appears in system commands has been redefined to 
a device/file number. It is a one- to five-digit number that specifies the 
device and file number where a workspace is to be saved or loaded. If the 
number is less than four digits, it is only the file number; default device is 
assumed: otherwise, the high-order one or two digits is the device number. 


The following commands are not supported because they apply only to 
multiterminal systems and remote systems: 


JOFF: )OFF HOLD; )CONTINUE HOLD; )PORTS; )MSGN; )MSG; )OPRN; 
)OPR; all special system operator commands 


The following commands are not supported because the function is not 
supported: 


)GROUP; )GRPS; )GRP 
The following commands are not supported: 
JORIGIN; )WIDTH; )DIGITS 


They are available with the system variables 110, DPW, and LPP, 
respectively. 
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e The following commands have been added to support the 5110 processor 
and its input/output devices: 


)MARK — To format files 

JOUTSEL — To specify which transactions are to be printed 
)REWIND — To rewind the tape unit 

)JRESUME — To load a stored workspace and reestablish the 


system environment 


)FILEID — To change the file name on a diskette volume 

)FREE — To make a diskette file space available for 
reallocation 

)PROTECT — To change the write-protect indicator 

)VOLID — To change the volume ID or access protect indicator 

)LINK ~— To load microcoded programs 

)PROC — To open a procedure file 

)SORT — To transfer control to the sort utility 


« The )CONTINUE command has been changed to save workspaces with 
suspended functions. The parameters are the same as )SAVE but the stored 
workspace cannot be copied or loaded into a 5110 with a smaller active 
workspace. 


e« Since the 5110 system is not in a communications environment, the 
RESEND message will not occur. 


« 5110 is implemented with only one workspace area (no spare); therefore, 
the following error messages have been added: 


1. Function name [statement number] LINE TOO LONG — Cannot save 
functions with statements greater than 115 characters. 


2. WS TOO BIG — Workspace is too big to fit in the active workspace. 


3. NOT WITH SUSPENDED FUNCTION — Only the )CONTINUE command 
will work to write the workspace to tape. 


« For diagnostic reasons, occurrence of SYSTEM ERROR does not clear the 
workspace. The following message occurs when you attempt anything other 


than )CLEAR after a system error: 


NOT WITH SYSTEM ERROR 


« Saved workspaces are not time-stamped and dated because the information 
is not available in this system; therefore, the following messages now occur 
after library operations: 


COPIED 
LOADED 
SAVED 
CONTINUED 
DROPPED 


device/file 
device/file 
device/file 
device/file 
device/file 


wsid 
wsid 
wsid 
wsid 
wsid 


e The )LIB command does more than list the saved workspaces. It lists all the 
files on the specified device. The response, therefore, contains more 


information (see )LIB command is Chapter 3). 


e« The following system messages have been added for the new system 


commands and input/output operations: 


ALREADY MARKED 


DEVICE NOT OP 
ERROR eee d 


EXCEEDED MAXIMUM RECORD LENGTH 


EN 


INVALID DATA TYPE 
INVALID DEVICE 
INVALID DEVICE NUMBER 


INVALID FILE 


INVALID FILE NUMBER 
INVALID OPERATION 
INVALID PARAMETER 


MARKED b n 


NOT WITH OPEN FILE 
NOT WITH OPEN DEVICE 
FILE NOT FOUND 

FILE NOT UNIQUE 
WRITE PROTECT 

CTL DOMAIN ERROR 


INVALID DAT 
NO DAT 


WRONG VOLUME 
INVALID DISK FILE NAME 


LINE TOO LONG 
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« The shared variable processor on the 5110 is designed to provide an 


interface between only one APL user and one I/O processor. Thus, only 
one processor number is supported (1). 


The response to DSVO is 2, since, if it is a valid share, it is always 
accepted before the APL user regains control. (If an unsupported processor 
is specified, the response is 1.) 


The response to IISVR is the same as the response to USVO. 


Being strictly a sequential machine, the only mode of interaction is reversing 
half-duplex; that is, the |/O processor always responds to each action by 
the APL user. Therefore, the access control vector (ISVC) is always 1 1 1 
1 for sequential operations and the CTL shared variable for direct access 
operation. 


Because there are never any outstanding offers, 0SVO always returns an 
empty vector. 


This is a single user system without an internal clock; therefore, the 
following system variables and functions are supported as follows: 


Default Value 


OTS — Time stamp 1900 000000 
OAI — Accounting information 0000 

OTT — Terminal type 

OUL — User list 1 

ODL — Delay ) 


The I-beam functions have been replaced with system variables or system 
functions and are not supported. 


Catenation using semicolons had been replaced for format, but it is still 
supported on the 5110. 


Data can be exchanged between APL and BASIC or other systems via 
communications; therefore, the following characters have been added to the 
APL character set: 


$, #, @, &, , aj %, - 


The display screen is 64 characters wide; therefore, the initial values of 
CIPW and OPP system variables are 64 and 5 instead of 120 and 10. 


If the print width is altered to something greater than 64, any output that 
exceeds 64 characters is wrapped to another line on the display screen. 


Bare (f) output followed by bare ([]) input yields a different reply. For 
APLSV, the | input is prefixed by the same number of blanks as the 
previous [§ output. For 5110 APL, the [) input is prefixed by the previous [ 
output. (See Chapter 6 for more information on bare output followed by 
bare input.) 


¢ The display screen provides the ability to edit lines of data directly; 
therefore, the following changes were made to function definition: 


[NO] — Now displays line N in the display screen lines 1 and O for 
editing. 
[NOM] -— Has the same result as [NU]; the M is erased when the 


EXECUTE key is pressed. 


[AN] — Allows line N to be deleted. N must be a single line 
number. 


The use of the ATTN key to delete a line works, but only in function 
definition mode, not while entering function definition mode. 


To prevent problems when displaying or editing statements in a 
user-defined function, the print width (OPW) is automatically set to 128 
when the 5110 is in function definition mode. The print width 
automatically returns to its previous setting when the function definition 
is closed. 


There is only limited editing space; therefore, function statements that 
are greater than 115 characters cannot be edited, and the message LINE 


TOO LONG is displayed. 


e The 5110 will insert a quote if an uneven number of quotes is entered. 
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Error Message 


ALREADY MARKED 


DEFN ERROR 


Cause 


The specified file was previously 
marked. 


An invalid request to use the function 
definition mode was made: 


@ A Vsymbol was erroneously used 
in a statement. 


@ An attempt was made to reopen a 
locked function. 


@ An attempt was made to reopen a 
function using more than just the 
function name. 


@ An attempt was made to open a new 
function definition using the name 
of a previously defined global 
variable name. 


@ An invalid edit request was made in 
function definition mode. 


@ An attempt was made to edit a 
pendent function. 


Appendix F. Error Messages 


Error messages can result when you incorrectly use APL primitive (built-in) 
functions, user-defined functions, system commands, system variables, or 
input/output operations. The following list contains the APL error messages 
along with some possible causes for the error condition and a suggested user’s 


User’s Response 
If the file(s) is to be re-marked, enter GO. 
Note: For tape files, any existing data in 


the files following the last re-marked file 
will no longer be available. 


If the statement was intended to open or 
close a function, the V is valid only in the 
beginning and ending positions. 


Enter a corrected statement. 


Enter a different function name or erase 
the global variable. 


Enter a valid edit request. 


If the suspended function execution can 
be terminated, clear the state indicator, 
then edit the function. 
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Error Message 


DEVICE NOT OPEN 


DOMAIN ERROR 


ENTRY ERROR 
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Cause 


An attempt was made to read a data 
file, and an input operation to the file 
has not been specified. 


The function indicated by the caret (A) 
cannot operate on the arguments given: 


@ The result exceeds the capacity of 
the 5110 (< 7.237...£75or 
>7.237 ... E75). 


@ Acharacter argument cannot be 
used in an arithmetic operation. 


@ The argument is not mathematically 
defined for the function (that is, 


12+ 0). 


@ Numeric and character data cannot 
be cantenated together. 


@ Anerror occurred in a locked 
function. 


@ Format length is incorrect. 


An invalid character was entered. 


User’s Response 


Assign the information required to 
specify the input/output operation to the 
shared variable. 


Determine the correct arguments for the 


function in error. Then correct the 
statement in error. 


Enter a corrected statement. 
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The input/output device errors are displayed in the format ERROR eee ddd, 
where eee is the error code and ddd is the device number. The device 
numbers are: 500—printer; 001—built-in tape unit; O02—auxiliary tape unit; 
011-diskette drive 1; 012—diskette drive 2; 013-diskette drive 3; 014—diskette 
drive 4. 


Many of the input/output errors relating to tape or diskette can be the result 
of a machine problem or a problem with the tape or diskette itself. Some 
problems that can be encountered with the tape or diskette are: 

e Poor or worn oxide coating 

¢ Binding tape cartridge spools 

¢ Tape cartridge drive band off 

¢ Diskette binding in the envelope 

¢« Diskette drive hole worn too large or off center 

e Diskette index hole off location 

Error codes 004 to 008 for tape and error codes 015 and 045 for diskette can 

be caused by the conditions listed previously, as well as by the causes listed 
next. You might save yourself time and any expenses associated with a service 
call if you make a thorough check of your media (tape or diskette) before 


calling your service representative. 


Following is a list, additional causes, and user’s response for the input/output 
device error messages. 


Error Message Cause User’s-Response 


ERROR 001 ddd Diskette drive timing malfunction. Try the operation again. If the error 
occurs a second time, call your service 
representative. 


ERROR 002 ddd Command error. 

ERROR 003 ddd Tape error. Try the operation again. If the error 
occurs a second time, call your service 
representative. 

ERROR 004 ddd Tape error or second tape not ready. 


An attempt was made to perform tape § Use the )MARK command to mark the 
operations with an unmarked tape. tape. Then try the operation again. 


Uneven winding of the tape. Move the tape to its limits using the 
procedure described under Tape Data 
Cartridge Handling and Care, in Chapter 2. 


The tape head needs cleaning. Clean the tape head using the procedure 
described under Tape Head Cleaning 


Procedure, in Chapter 2. 
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Error Message 


ERROR 005 ddd 


ERROR 006 ddd 


ERROR 007 ddd 


ERROR 008 ddd 


ERROR 009 ddd 


ERROR 010 ddd 


ERROR 011 ddd 


ERROR 012 ddd 
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Cause 


The tape cartridge is not inserted in 
the indicated tape unit. 


An attempt was made to write on a 
tape that is file-protected. (The SAFE 
switch on the tape cartridge is in the 
SAFE position.) 


Tape read error. 


A machine malfunction might have 
occurred when data was being written 
or the tape cartridge might have been 
removed from the tape unit when data 
or a workspace was being written to 
tape. 


An attempt was made to read a record 
after the EOD address. 


Data is to be written to a data file, but 
all the space in the file has been used. 


An attempt was made to write the 
active workspace on tape with a SAVE 
command, but the specified file could 
not contain all the information from 
the active workspace. 


For record |/O operations, an attempt 
was made to write a record after the 


end of data. 


A file number was specified that does 
not exist on the tape. 


The end of the tape has been reached. 


User’s Response 


Insert a tape cartridge and try the 
operation again. 


If you want to write on the tape, set the 
SAFE switch on the tape cartridge off the 
SAFE position. 


Use the )LINK command to !oad the tape 
recovery program to recover as much data 
as possible. 


Try the operation again. If the error 
occurs again, copy the files following the 
file that caused the errors onto another 
tape. Also, if the file is a saved work- 
space file, some of the data in the file 
might be retrieved if you use the )COPY 
command. Then use the MARK 
command and re-mark the tape from the 
file that caused the error. 


Use the MARK command to format a 
larger file and do the operation again. 


Use a larger file to save the active 
workspace. 


Specify the correct file or use the JMARK 
command to mark the tape. 


Use another tape cartridge. 


Error Message 
ERROR 013 ddd 


ERROR 014 ddd 


ERROR 015 ddd 


ERROR 016-019 ddd 


ERROR 020-023 ddd 


ERROR 024 ddd 


ERROR 025 ddd 


ERROR 026-028 ddd 


ERROR 029 ddd 


ERROR 030 ddd 


ERROR 031 ddd 


ERROR 032-035 ddd 


Cause 
The specified device is not attached. 


Device error. 


An input/output error occurred when: 


@ The system was reading or writing 
the volume label. 


@ The system was reading or writing 


a file header. 


Faulty diskette. 


Hardware malfunction. 


There is no VOL1 label on the diskette. 


Invalid diskette. 


Hardware malfunction. 


A match was not found for a search 
by key operation. 


The diskette drive cover was opened 
between accesses to the device. 


Faulty diskette. 


1/O processor error. 
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User’s Response 


Try the operation again. If the error 
occurs a second time, call your service 
representative. 


Use the initialization utility to reinitialize 
the diskette. 


Copy all available data onto another 
diskette, and then use the initialization 
utility to reinitialize the diskette. 


Copy all available data onto another 
diskette, and then use the initialization 
utility to reinitialize the diskette. 


Try the operation again. If the error 
occurs a second time, call your service 
representative. 


Use the initialization utility to initialize 
the diskette. 


Use the initialization utility to initialize 
the diskette. 


Try the operation again. If the error 
occurs a second time, call your service 
representative. 


See Chapter 7 for a description of search 
by key operation. 


Close the diskette drive cover, and try the 
operation again. 


Copy all available data onto another 
diskette, and then use the initialization 
function to reinitialize the diskette. 


Try the operation again. If the error 


occurs a second time, call your service 
representative. 
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Error Message 


ERROR 036 ddd 


ERROR 037 ddd 


ERROR 038 ddd 


ERROR 039 ddd 


ERROR 040 ddd 


ERROR 041 ddd 


ERROR 042 ddd 


ERROR 043 ddd 


ERROR 044 ddd 
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Cause 


An attempt was made to use the 
JMARK command to mark a file, and 
one of the following conditions 
occurred: 


@® More than the maximum number 
of files allowed on the diskette 
was specified. 


@ Not enough continuous space was 
available on the diskette for the 
file. 


1/O processor error. 


1/O processor error. 


Invalid file header. 


An attempt was made to write to a 
write-protected file. 


An 1/O operation was specified with 
only the file 1D, and more than one file 
on the diskette have the same file ID. 


An 1/O operation was specified with 
only the file 1D, and no matching file 
1D was found. 


The file name already exists on the 
diskette. 


A )MARK command was issued, but 
there is not enough unallocated 

continuous bytes of storage available 
on the diskette to format the file(s). 


An attempt was made to access 
a volume protected diskette. 


An attempt was made to access a bad 
sector in the data file. 


User’s Response 


Mark the files on another diskette. 


Use the compress function to place all 
the unallocated diskette space in one 
continuous area, or mark the file on 
another diskette. 


Try the operation again. If the error 
occurs a second time, call your service 
representative. 


Try the operation again. If the error 
occurs a second time, call your service 
representative. 


Copy all available data onto another 
diskette, and then use the initialization 
function to reinitialize the diskette. 


If you want to write to the file, use the 
)PROTECT command to remove the 
write-protect indicator and then write to 
the file. 


Issue the command using the appropriate 
file number. 


Insert the correct diskette and reissue the 
command, or reissue the command using 
the correct file ID. 


Issue the command or statement using a 
new file !D. 


Use the compress function to position all 
the unallocated storage as continuous 
bytes. Then try the JMARK command 
again. If the error occurs again, use 
another diskette. 


Use the )VOLID command to turn off the 
volume protection indicator. 


See return code 22 n in Chapter 7. 


Error Message 


ERROR 045 ddd 


ERROR 047-049 500 


ERROR 050 500 


ERROR 051 500 


ERROR 052-053 500 


ERROR 054 500 


ERROR 055-059 500 


ERROR 070-072 


EXCEEDED MAXIMUM RECORD 
LENGTH 


Cause 


The diskette is inserted incorrectly. 


Printer errors. 


The printer has run out of forms. 


The printer POWER ON/OFF switch 
is turned off. 


Printer errors. 


The printer was turned off within two 
seconds after a system command was 
entered. The error continues to occur 
when the printer is turned on again. 


Printer errors. 


Processor error. 


The tape or diskette was removed 
before an input/output operation 
was terminated (see Chapter 7). 


When the tape or diskette copy utility 
was used, a header record was changed 
to specify a maximum record length 
less than the largest record in the file. 
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User’s Response 


Make sure the diskette is inserted 
correctly and try the operation again. 


Try the operation again. If the error 
occurs a second time, call your service 
representative. 


Insert forms in the printer (see Chapter 8). 


Turn the POWER ON/OFF switch on. 


Check to be certain that both the forms 
tractor pins and platen are not engaged 
simultaneously. If the error occurs a 
second time, call your service 
representative. 


Save any data or user-defined functions in 
the active workspace, then enter the 
)CLEAR command to get the printer into 
synchronism with the 5110. 


See ERROR 052-053 500. 
Try the operation again. If the error 
occurs a second time, call your service 


representative. 


The data in the file cannot be used. 


Use the tape or diskette copy utility and 
copy the tape containing the invalid 
header record again, this time specifying 
a larger maximum record length. 
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Error Message 


FILE NOT FOUND 


FILE NOT UNIQUE 


IMPLICIT ERROR 


240.2 


Cause 


A system command or |/O operation 
was specified with only the file ID, 
and no matching file ID was found. 


The file name already exists on the 
diskette. 


A system command was issued 
specifying only the file 1D, and more 
than one file on the diskette has the 
same file ID. 


The system variable that precedes the 
error message was previously assigned 
an invalid value or was undefined in a 
function due to the system variable 
being made local to the fucntion. 


Note: This error message is not 
displayed until the system variable in 
error is used by the APL system. 


User’s Response 


Insert the correct diskette and reissue the 
command, or reissue the command using 
the correct file 1D. 


Issue the command or statement using a 
new file ID. 


Issue the command using the appropriate 
file number. 


Assign a valid value to the system variable 
(see Chapter 5). 


Error Message 


INCORRECT COMMAND 


INDEX ERROR 


INTERFACE QUOTA EXHAUSTED 


INTERRUPT 


INVALID DATA TYPE 


INVALID DEVICE 


Cause 


A system command was entered 
incorrectly: 


@ The command keyword was not a 
valid keyword. 


@ One of the parameters was entered 
incorrectly. 


@ Too many parameters were entered 
for the command. 


The index values given are outside the 
boundaries of the array, or a primitive 
function or APL operator being 
subscripted by index [I] has been given 
an argument that does not have an Ith 
dimension. 


An attempt was made to establish 
more than 12 variable names as shared 
variables. 


The shift key was held down and the 
ATTN key pressed when the 5110 was 
processing data, or an invalid 
input/output operation was attempted. 


An attempt was made to write to an 
interchange format file (TYPE = 1), 
but the data is not a character scalar 
or vector. 


An attempt was made to specify an 
input/output operation with other 
than character data. 


The data assigned to the shared variable 
is not the correct shape and 
representation for the creation of direct 
access APL internal format data file. 


A device was specified that does not 
exist or is incorrect for the operation 
to be performed. 


User’s Response 


Enter the command in its correct form. 


If a variable is being indexed, check its 
shape (op A) against the index values. 


If a primitive function or operator is 
being indexed, determine the rank(s) 

(00 A) of its argument(s); then check the 
index to see if it is equal to or less than 
the required rank. 


Check the index origin ([].70) to ensure 
that it is consistent with the statement 
being executed. 


Retract any unused share variable names. 


If an invalid input/output operation was 
attempted, check to make sure the 
operation was specified correctly. 


Change-the data to a character scalar or 
vector. 


Enclose the information required to 
specify the input/output operation in 
single quotes. 


You must assign data to the shared 
variable that is the same shape and 
representation as the first record written 
to the file. 


Specify the correct device number. 
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Error Message 


INVALID DEVICE NUMBER 


INVALID DISK FILENAME 


INVALID FILE 


INVALID FILE NUMBER 


INVALID PARAMETER 
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Cause 


A device number that does not exist 
was specified. 


An attempt was made to use an invalid 
diskette file name. 


The file type is not valid for the 
attempted operation. For example, 

an attempt was made to load a data file 
or read a workspace file. 


An attempt was made to access a file 
number that is 1 larger that the last 
marked file. 


An attempt was made to load or copy a 
damaged file. The file was probably 
damaged by the tape being removed 
from the tape unit before a save 
operation was complete. 


The wrong file ID was specified. 


An attempt was made to load a 5100 
continued file (file type 6) into a 5110. 


An attempt was made to use a file 
type 2 (interchange file) as a 
procedure file. However, the file 
has records that exceed 128 
characters, or the BASIC SAVE 
DATA command was used to create 
the file. 


The file number 0 was specified for a 
)LOAD, )SAVE, )CONT, )DROP, 
JCOPY, or )PCOPY command. 


An attempt was made to specify an 
input/output operation to a data file, 
but the file number was not valid. 


A keying error was made, or an 
incorrect parameter was entered when 
you specified an input/output 
operation. 


A keying error was made when you 
entered the parameters for a system 
command. 


User’s Response 


Specify the correct device number. 


Change the name to a valid file name (see 
Variable and File Names in Chapter 2). 


Use the )LIB command to determine the 
file type. 


Specify the correct file number. 


The data in the file is unusable. The file 
can be dropped (use the )DROP 
command) and reused. 


Use the )LIB command to find the 
correct file 1D, and reenter the statement. 


Load the file into a 5100, and store the 
file on tape using the SAVE command. 
Then load the saved file into the 5110. 


Use shared variables to read the file, and 
then rewrite the file with no records 
exceeding 128 characters. 


Reenter the command specifying the 
correct file number. 


Use the )LIB command to find the 
correct file number. Then reenter the 
information required to specify the 
input/output operation. 


Enter the information required for the 
input/output operation or system 
command again, correcting the keying 
errors. 


Esroy Message 


lOSTATUS: INVALID OPERATION 


LENGTH ERROR 


LINE TOO LONG 


NONCE 


Cause 


An invalid input/output operation was 
attempted, such as: 


@ An attempt was made to read the 
file header in other than 
nontranslate mode (TYPE = N). 


@ The shared variable was referenced 
more than once to check the return 
code. 


@ A processor other than 1 (the left 
argument for the [] SVO function) 
was established for the shared 
variable. 


This message is followed by the 
INTERRUPT error message. 


The shapes of the two arguments are 
not valid for the function indicated by 
the caret (A). 


An attempt was made to edit a 
statement (in a user-defined function) 
that is greater than 115 characters. 


An attempt was made to save a 
workspace that contained a 
user-defined function with a statement 
having more than 115 characters. In 
this case, the error message is preceded 
by the function name and the statement 
number that caused the error. 


An |-beam function was used. These 
functions are not used in the 5110 
APL system. 


An attempt was made to index a 
portion of an array with a rank greater 
than 14. 


An attempt was made to use a take or 
drop operator on an array with a rank 
greater than 9. 


An attempt was made to laminate an 
array with a rank greater than 20. 


User’s Response 


Respecify the operation using the 
TYPE = N parameter, and then try the 
operation again. 


Assign the return code to another variable 
if the return code must be checked more 
than once. 


Retract the shared variable offer, and 
then make the offer again using a 1 as the 
left argument for the [] SVO function. 


Make sure the arguments are valid for the 
function. Then reshape (restructure) the 
arguments. 


Break up the statement into two 
statements, or use the [JCR and [JFX 
functions to edit the statement. 


Use the [JCR function to make the 
user-defined function a matrix; then save 
the workspace on tape. 


Do not use the I-beam functions. 


Display the entire array, or break the 
array into smaller sections. 


Break the array into smaller rank arrays. 


Break the array into smaller rank arrays 
and reshape. 
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Error Message 


NOT COPIED: names 


NOT FOUND: names 


NOT SAVED, 
THIS WS IS workspace ID 


NOT WITH OPEN DEVICE 


NOT WITH SUSPENDED FUNCTIONS 


NOT WITH SYSTEM ERROR 


RANK ERROR 
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Cause 


A )PCOPY was issued, but each object 
named in the message was not copied. 
The active workspace already contained 
a global object with the same name. 


A )COPY was issued, but each object 
named in the message was not copied. 
The active workspace already contained 
a shared variable with the same name. 


An )ERASE command was issued, but 
the global objects named in the message 
were not found in the active workspace. 


A )COPY or )PCOPY command was 
issued, but the specified global object 
does not exist in this specified 
workspace. 


A )SAVE or )JCONTINUE command 
was issued, but the stored workspace 
1D is not the same as the active 
workspace ID. 


An attempt was made to issue a system 
command or specify an input/output 
operation to a tape unit that is already 
being used for input/output operations. 


An )OUTSEL command was issued, 
but printer output has been specified 
for a shared variable. 


An attempt was made to doa )SAVE, 
)COPY, or )PCOPY operation, and the 
active workspace contains a suspended 
function or an open request for quad 
input. 


An attempt was made to do an 
operation other than )CLEAR after a 
SYSTEM ERROR occurred. 


An attempt was made to use a function 
that requires the rank of the arguments 
to conform, but they do not. For 
example, a function requires the rank of 
the arguments to be the same, but they 
are not. 


An attempt was made to use an 
argument whose rank is too large for 
the operation. 


The number of semicolons in the index 
does not equal the rank minus 1. 


User’s Response 


Issue a )JCOPY command if the named 
objects should be copied. 


Establish and use another shared variable 
name, and erase the existing shared 
variable name if the objects should be 
copied. 


Reissue the command using the carrect 
object names. 


Reissue the command using the correct 
object name or stored workspace. 


Use the correct ID or change identification 
of the active workspace, using the )WSID 
command; then reissue the SAVE 
command. 


Terminate the input/output operatian, or 
wait until the input/output operatian is 
complete before issuing the command ar 
specifying another input/output 
operation to the tape unit. 


Retract the printer shared variable offer, 


Clear the suspended function or request 
for quad input by using > (right arrow). 


(See SYSTEM ERROR.) 


Make sure the arguments are valid. Then 
reshape (restructure) the arguments sa 
that they have the correct rank (p 9A). 


Use the correct number of semicolons. 


Error Message 


S| DAMAGE 


SYMBOL TABLE FULL 


SYNTAX ERROR 


Cause 


The state indicator was made invalid 
because one of the following occurred: 


@ A function exists in the state 
indicator list, but the function was 
erased. 


@ A suspended function's header was 
changed or displayed [O[]] . 


@ A label was added, removed, or 
changed on the suspended statement. 


More symbols were used than the 
number of symbols allowed. 


The symbol table in the stored 
workspace is full, and a load operation 
was attempted. This error is caused by 
the latent expression variable even if it 
has not been assigned. 


The part of the statement indicated by 
the caret (A) is syntactically invalid. 


The symbol used for the APL built-in 
function is not a valid symbol. 


User's Response 


Use the )SI or )SINL command to display 
the state indicator. Clear out the state 
indicator by entering > for each «in the 
)SI list. 


Use the SAVE command to save the 
workspace, use the )CLEAR command to 
clear the active workspace, increase the 
number of symbols allowed by using the 
)SYMBOLS command, then use the 
)COPY command to copy the stored 
workspace into the active workspace. 


Note: Erasing a symbol from the active 
workspace does not remove it from the 
symbol table however, saving the active 
workspace and loading it again will 
remove any unused symbols from the 
symbol table. 


\ 
Enter a corrected statement. Be sure to 
check for the correct number of 
parentheses and arguments. 


See Appendix B for a list of the 
characters that can be confused with valid 
APL built-in functions. Reenter the 
statement using the correct symbol for 
the APL built-in function. 
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Error Message 


SYSTEM ERROR 


VALUE ERROR 


WRITE PROTECTED 


WRONG VOLUME 
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Cause 


A malfunction occurred in the APL 
system program, and the data in the 
active workspace is lost. 


An attempt was made to load a stored 
workspace file after the file header was 
changed by the tape or diskette copy 
utility. 


The object indicated by the caret (A) 
has not been given a value: 


@ If the object is a variable name, the 
variable was not previously assigned 
a value. 


@ If the object is a function name, the 
function header did not specify a 
result, the function did not assign a 
value to the result variable, or the 
function does not exist. 


An attempt was made to write 
information to a diskette file, and the 
write-protect indicator is on. 


An attempt was made to read from or 
write to a diskette data file, and the 
diskette is not on the same diskette 
drive as when the operation was 
specified. 


The RESUME command was issued and 
the diskette with the data file is not in 
the same drive as when the original 


input/output operation was specified. 


User’s Response 


Enter the )CLEAR command; if the error 
continues to occur, call your service 
representative. 


Note: There might be some system data 
areas displayed with this message. 


If SYSTEM ERROR occurred on a load 
or copy operation, the error may be 
caused by a bad stored workspace file. 
Try loading or copying another stored 
workspace file to see if the error occurs 
again. 


Enter )CLEAR and use the )COPY 
command to copy the stored workspace 
into the active workspace. Then use the 
)SAVE command to write the data back 
onto the stored workspace file. Now, the 
)LOAD command can be used to load the 
stored workspace into the active 
workspace. 


Assign a value for the indicated variable 
or correct the function so that it has an 
explicit result, The value must be 
assigned before the object is used. 


if the information is to be written to the 
file, enter PROTECT file number OF F 
to remove the write-protect indicator. 


Place the diskette containing the data 

file in the same diskette drive as when the 
input/output operation was specified, and 
try the operation again. 


Error Message 


WS TOO BIG 


Cause 


One of the following conditions 
occurred: 


An attempt was made to load a 
workspace stored with the 
JCONTINUE command into a 5110 
with less internal storage. 


An attempt was made to load a 
workspace stored with the 
JCONTINUE command into the 
active workspace, but IMFs have 
been applied, reducing the 
available internal storage. 


An attempt was made to write the 
active workspace (using the 
JCONTINUE command) into a file 
that is too small. 


User’s Response 


Use a 5110 with enough internal storage. 


Restart to clear the IMF, load the stored 
workspace into the active workspace, 
)SAVE the active workspace, apply the 
IMFs, then load the stored workspace 
again or copy only the required objects. 


Use a file that is large enough. 
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Error Message 


WS FULL 


WS LOCKED 


WS NOT FOUND 
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Cause 


One of the following conditions 
occurred: 


A )COPY or )PCOPY command 

was issued, but the active workspace 
could not contain all of the objects 
requested. 


The active workspace could not 
contain all the information required 
to build a define function. 


The active workspace could not 
contain the intermediate results of 
an APL expression. 


The active workspace could not 
contain information required to do 
input/output operations. 


A workspace was written to tape 
with a SAVE command, but the 
extra storage required to load the 
stored workspace back into the 
active workspace exceeds the 
available storage. 


Too many symbols were specified 
in a SYMBOLS command. 


The workspace is password-protected, 


but no password or the wrong password 


was specified in the command. 


The workspace is not 
password-protected, and a password 
was specified. 


A )LOAD, )DROP, )COPY, or )PCOPY 
command was issued, but there is no 


stored workspace with the identification 


specified in the command. 


User’s Response 


Erase unnecessary objects. If there is still 
not enough space: 


— Partition the workspace into two or 
more workspaces with related 


functions. 


— Store data in a separate workspace or 
in a data file. 


— Reprogram using smaller intermediate 
results. 


— Clear the state indicator with > if 
suspended functions exist. 


— Reduce the size of the symbol table. 


See note under )SYMBOLS. 


Use the )COPY command to make the 
stored workspace into two workspaces. 


Reenter the command with the correct 
password specified. 


Reenter the command with the correct 
password specified. 


Enter without a password. 


Reenter the command with the correct 
workspace identification. 


Appendix G. Attaching a TV Monitor 


Generally, modifying a standard TV set and using it as a video monitor yields 
less satisfactory results than a regular video monitor. This is because the same 
level of quality is not built into TV receivers as is found in monitor class units. 
For example, the contrast and resolution are not as good on a modified TV 
receiver; thus the image is not as sharp and usually more difficult to read. 


However, if you choose to modify a TV receiver and use it as a video monitor 
you must observe the following or you may damage the 5110 and expose 
yourself to a severe electric shock when you attempt to hook up the TV set to 
the IBM 5110. 


A modified TV set must have isolation between the primary line voltage and 
the set’s chassis and circuitry. You can usually accomplish this by using an 
isolation transformer between your outlet line voltage and the input voltage to 
the TV set. This transformer should be permanently wired into the circuit. The 
new input power plug must be a three-prong grounded plug with the ground 
connected to the chassis of the TV set. This grounding circuit must be 
electrically connected to the 5110 grounding circuit. 


Before the video input is connected to anything, it should be tested to verify 
that the connector’s external shell is at ground potential and that no line 
voltage is present on either the external shell or the center conductor. 


It is the responsibility of the TV modifier to ensure that the input circuit meets 


the requirements of the 5110 output and will not damage the 5110. 


Three-Prong Isolation TV Output 
Grounded Plug Transformer Connector 


Note: If you do elect to modify a TV receiver for use as a video monitor, IBM 
accepts no responsibility for safety precautions during conversion and hookup, 
for damages incurred to the TV receiver or 5110, or for the quality of the TV 
receiver as a video monitor. 
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IBM is grateful to the American National Standards 
Institute (ANSI) for permission to reprint its definitions 
from the American National Standard Vocabulary for 
Information Processing (Copyright 1970 by American 
National Standards Institute, Incorporated), which was 
prepared by Subcommittee X3K5 on Terminology and 
Glossary of the American National Standards Committee 
X3. 


ANSI definitions are identified by an asterisk. An 
asterisk to the right of the term indicates that the entire 
entry is reprinted from the American National Standard 
Vocabulary for Information Processing. 


active referent: The usage of a name that was most 
recently localized, or the global usage if the name is not 
localized. 


active workspace: A part of internal storage where 
data and user-defined functions are stored and 
calculations are performed. 


ADD operation: An operation using a shared variable 
to add information to an existing data file. 


alphameric keys: The keys on the left side of the 
keyboard whose arrangement is similar to that of a 
typewriter keyboard. 


APL internal data format: See internal data format. 
arguments: Data supplied to APL functions. 

array: A collection of data that can range from a single 
item to a multidimensional data configuration. Each 
element of an array must be the same type as the other 


elements (all characters, all numeric, or all logical). 


assign: To use the « (assignment arrow) to associate a 
name with a value. 


available storage: The number of unused 1024-byte 
blocks of storage in a file on tape. 


bare output: Output displayed without the cursor 
returning to the next line. 


Glossary 


basic data exchange: A diskette data exchange format 


‘that uses 128-byte sectors. The basic exchange format 


allows you to exchange data between the 5110 and 
other IBM systems. For example, data recorded on the 
diskette using a 3741 can be processed using a 5110. 


branch instruction: An instruction that modifies the 
normal order of execution indicated by the statement 
members. Branch instructions always begin with a > 
(branch arrow). 


branching: Modifying the normal order of execution 
indicated by the statement numbers. 


built-in function: See primitive function. 


byte: A unit of storage. For example, a character takes 
1 byte of storage. 


character constants: Characters that do not represent 
numbers, variables, or functions. Character constants 
are enclosed in single quotes when they are entered 
(except for Minput); however, the single quotes do not 
appear when the character constants are displayed. 


command keyword: The name of a system command 
including the right parenthesis. For example, the 
command keyword for the )MARK command is )MARK. 


comment: An instruction or statement that is not to be 
executed. A comment is indicated by a A as the first 
character. 


conditional branch: A branch that is taken only when a 
certain condition is true. 


coordinate: A subset of data elements in an array. For 
example, a matrix has a row coordinate and a column 
coordinate. 


cursor: The flashing character on the display that 
indicates where the next input from the keyboard will be 
displayed. 


data file: A file on tape or diskette (file type 02, 08, 09, 


10, or 15) where data is stored by means of a share 
variable. 


Glossary 251 


defective record: A 512-byte block of storage on tape 
that cannot be read. 


device/file number: A number that specifies the device 
and file to be used for input or output operations. 


direct access data file: A diskette data file in which 
records can be read from or written to by means of a 
specified record number. 


DISPLAY operation: An operation using a pair of 
shared variables to read and write data on the display 
screen. 


dual-language machine: A 5110 that can execute 
either APL or BASIC statements. 


dyadic functions: Functions that require two arguments 
(a right and a left argument). 


editing: Modifying an instruction or statement that 
already exists. 


element: The single item of data in an array. 


empty array: A variable that has a zero in its shape 
vector. The array has no (zero) elements. 


execute: To press the EXECUTE key to process data 
on the input line. 


execution: The processing of data. 


execution mode: The mode that is operative when 
statements or functions are executed. Contrast with 
function definition mode. 


explicit result: The result of a function that can be 
used in further calculations. The function must contain a 
result variable if it is to have an explicit result. 


file: A specified amount of storage on the media. The 
media is formatted into files by the MARK command. 


file ID: The name of a file on the media. If the file 
contains a stored workspace, the file ID is the same as 
the stored workspace ID. 


file type: The identification of the type of data stored in 
a file. 


function body: The statements within a user-defined 


function. These statements determine the operation(s) 
performed by the function. 
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function definition: The definition of a new function (a 
user-defined function) to solve a problem. 


function definition mode: The mode that is used for 
defining or editing user-defined functions. The V 
symbol is used to change the mode of operation. 
Contrast with execution mode. 


function header: A definition that states the function 
name, number of arguments, local names, and whether 
or not the function will have an explicit result. 


general exchange data file: A file with data in the 
general exchange format. . 


general exchange data format: A data format 
consisting of all character scalars or vectors. This file 
can be used as a 5110 BASIC source file. 


global names: Names having a value or function that 
can be used within or outside a user-defined function 
unless the name has been made local to a user-defined 
function that is executing, suspended, or pendent. 
Contrast with local name. 


identity element: The value that generates a result 
equal to the other argument of a function. 


IN operation: An operation using a shared variable to 
read information from a data file. 


index entry [I]: (1) A value or values enclosed in 
brackets that select(s) certain elements from an array. 
(2) A value enclosed in brackets that determines the 
coordinate of an array to be acted on by a primitive 
mixed function. 


index origin: Either O or 1, and the lowest value of an 
index. The index origin is set to 1 in a clear workspace 
and can be changed by means of the LJIO system 
variable. 


INR operation: An operation using a pair of shared 
variables to read records from a direct access data file. 


IOR operation: An operation using a pair of shared 
variables to read records from or write records to a 
direct access data file. 


IORH operation: An operation using a pair of shared 
variables to read records from or write records to a 
direct access data file. 


input: Information entered from the keyboard or read 
from tape by means of a shared variable. 


input line: A line consisting of the 128 positions on 
lines O and 1 of the display screen. Any information on 
the input line will be processed when the EXECUTE key 
is pressed. 


instruction: A function or series of functions to be 
performed. 


integer: A whole number. 


interactive function: A user-defined function that 
requests input from the keyboard as it executes. 


internal data file: A file containing data in the internal 
data format. 


internal data format: The format in which the data is 
stored in the 5110. 


keyword: See command keyword. 


labels: Names that are placed on statements in a 
user-defined function for use in branching. 


latent referent: The usage of a name that has been 
made unavailable by a more recently called function. 
The usage for that name cannot be accessed. 


length: (1) The length of a vector is the number of 
elements in the vector. (2) The length of a coordinate of 
other arrays is the number of items specified by that 
coordinate. For example, a matrix has a row coordinate 
with the length of 2; therefore, the matrix has two rows. 


library: A tape cartridge or diskette where data is 
stored for future use. 


local name: A name that is contained in the function 
header and has a value specified to the user-defined 
function during the execution of that user-defined 
function. 


locked function: A function that cannot be revised or 
displayed in any way. The opening or closing V was 
overstruck with a ~. 


logical data: (Boolean data) Data that consists of all 
ones and zeros. 


matrix: A collection of data arranged in rows and 
columns (rank 2). 


media: Tape or diskette storage. 


mixed function: A function having results that may 
differ from the arguments in both rank and shape. 


monadic functions: Functions that require one 
argument. The argument must be to the right of the 
function symbol. 


multidimensional array: An array that has two or more 
coordinates. 


n-rank array: An array that has more than two 
coordinates (a rank of more than 2). 


niladic function: A user-defined function that does not 
require any arguments. 


numeric keys: The keys on the right side of the 
keyboard whose arrangement is similar to that of a 
calculator keyboard. 


object: A user-defined function or variable name. 


open data files: Tape or diskette data files that are 
currently being used for input and/or output operations. 


operators: Controls that have as their arguments dyadic 
primitive scalar functions. These arguments are applied 
to arrays in a specified way. 


OUT operation: An operation using a shared variable to 
write information into a sequential access data file. 


OUTF operation: An operation using a shared variable 
to write information (sequentially) to a direct access data 
file. 


output: The results of statements processed by the 
5110. 


overstruck character: A character formed by entering 
one character, backspacing, and entering another 
character. Only certain combinations of characters can 
form overstruck characters. 


parameters: (1) Information needed by a system 
command (such as device/file number). (2) Information 
required to open a data file or to specify printer output. 


password: A sequence of characters that must be 


matched before the contents of a stored workspace can 
be loaded or copied into the active workspace. 
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pendent function: Any function in the state indicator 
list that is not a suspended function. 


physical record: A 512-byte block of storage on tape 
or one sector on diskette. 


plane: The third coordinate of an n-rank array (planes, 
rows, and columns). 


primitive function: The functions that are part of the 


APL language (such as , + - + X). 


PRT operation: An operation using a shared variable to 
output data on the printer. 


rank: The number of coordinates of an array (p ¢). 
record: Data assigned to a shared variable. 


result variable: A variable to the left of the assignment 
arrow in the function header where the results of the 
function are temporarily stored for use in further 
calculations. 


return code: A code assigned to a shared variable to 
indicate whether or not the operation was successful. 


scalar: A single data item that does not have a 
dimension (0 = pp DATA). 


scalar function: A function that is applied to 
corresponding elements in arguments. The results of 
scalar functions are the same shape as the arguments. 


scale: An integer representing the power of 10 in 
scaled representation. 


scaled representation: A value stated in a convenient 
range and multiplied by the appropriate power of 10. 


scroll: To move the information on the display screen 
up or down. 


shape: The length of each coordinate of an array. 


sector: A portion of a diskette cylinder. A sector can 
be 128, 256, 512, or 1024 bytes; however, all sectors 
on a diskette cylinder must have the same number of 
bytes. 


sequential access data file: The data in the data file 


must be retrieved in the same order as the data was 
written to the data file. 
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shared variable: A variable shared by the active 
workspace and shared variable processor. Used to 
transfer data for input/output operations. 


significant digit: *A digit that is needed for a certain 
purpose, particularly one that must be kept to preserve a 
specific accuracy or precision. 


single-element array: An array with a shape of all 1's; 
for example, a matrix with one row and one column. 


state indicator: An entry that contains information on 
the progress (statement number of the statement being 
executed) of user-defined function execution. Can be 
displayed to show all suspended and pendent 
user-defined functions and localized names. 


statement: A numbered instruction within a 
user-defined function. 


statement number: The number of a statement within 
a user-defined function. 


stop control (SA): A function that stops execution of a 
user-defined function before the execution of a 
specified statement. 


stop vector: A vector that specifies the statements 
when stop control is used. 


stored workspace: The contents of the active 
workspace stored on tape. 


strong interrupt: The result of holding down the shift 
key and pressing ATTN. The execution of an expression 
or a user-defined function is abandoned. Also, for 
user-defined functions, the pendent functions are 
cleared from the state indicator. 


suspended: See suspended function. 

suspended execution: See suspended function. 
suspended function: A function whose execution has 
stopped because of an error condition, the ATTN key 
being pressed, or stop control being used. 

system commands: A set of commands used to 
manage the active workspace and tape or printer 


operations. 


system functions: Functions used to change or provide 
information about the system. 


system operation: An operation that processes input 
data. 


system variable: A variable that provides controls for 
the system and information about the system to the 
user. 


trace control (TA): A function that displays the results 
of specified statements during the execution of a 
user-defined function. 


trace vector: A vector that specifies the statements 
used in trace control. 


transferring data: Using a shared variable to write data 
to tape, read data from tape, or output data to the 
printer. 


user-defined functions: New functions using the 
primitive functions but defined by the user. See function 


definition mode. 


variable name: A name associated with the value of a 
variable. 


variables: Data stored in the 5110. 


vector: An array with one dimension (1 = p p DATA). 


weak interrupt: The result of pressing the ATTN key. 
The execution of a user-defined function is suspended. 
Contrast with strong interrupt. 


workspace: See active workspace. 


workspace available: The amount of unused storage 
(number of unused bytes) in the active workspace 
(OWA). 


workspace ID: A name given to the contents of the 
active workspace. A stored workspace has the same 
name as the active workspace when the contents of the 
active workspace were written to tape. 
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@ (O-U-T) symbol 165 
CLEAR 32,35 
JCONTINUE 32,35 
)COPY 32 

)DROP 17,32 
JERASE 32,38 
)FILEID 32 

)FNS 33,39 
)FREE 32,40 
)LIB 23,33, 41 
JLINK 18, 33, 43 
JLOAD 32,44 
JMARK 23, 32,45 
JOUTSEL 33, 47 
JOUTSEL OFF 196 
)PCOPY 32,48 
)PROC 17,33, 49 
)PROTECT 32,50 
)RESUME 32,51 
JREWIND 23, 33, 52 
SAVE 32,52 

SI 33,53 

JSINL 33,53 
SORT 33,54 
SYMBOLS 32,54 
VARS 33,55 
)VOLID 32,56 
JWSID 32,57 

{tl 168 

(IN) 168 

[NCJ] 168 

[] (quad) 164 
[JAV 144 

[]cc 10,145 
[]cR 149 

[]cT 140 

[JEX 153 

[]FX 151 

[linput 18 

[]10 144 

[]LC 66, 143 
[]LX 143 

[]NC 154 

L]INL 153 

[]PP 142 

[]Pw 142 

[]RL 143 

[]SVO 177 

[]SVR 198 
[]SVR system function 
[]WA 143 
["}(quad quote) 164 
[input 18 

+O 159 

V symbol 134 


active workspace 14 

adapter for tv monitors 1 

add data toa datafile 179 
add data toafile 182 

ADD operation 179, 182, 187 
add statements 169 - 

adjust copy control dial 212 
alphabetic character mode 5 
alphabetic keys 4 

already marked message 18 
AND function 78 

APL character set 217 

APL characters 2 

APL command keyword 4 
APL internal code 185 

APL internal data format 181, 184, 185 
APL shared variable 177 
APLsymbols 4 

arccos 73 

arccosh 73 

arcsin 73 

arcsinh 73 

arctan’ 73 

arctanh 73 

arithmetic symbols 4 

assign an empty vector 197 
assignment arrow 136 
asynchronous communications 43 
atomic vector 144,219 
attention key 6 

audible alarm 29 

audible alarm control with []CC 147 
auxiliary tape unit 27 


backspace key 8 

bare output 166 

BASIC 2 

BASIC source file 181 
BASIC statement keyword 4 
BASIC/APL switch 2 

basis for general exchange 185 
binomial function 76 

blank character 8 

branch arrow 136 

branch instructions 160 
branching. 158 

brightness control 1 

built-in functions 59 

built-in tape unit 27 

bytes 13 

BO 185 


Index 


Index 
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canonical representation []CR 149 
catenate function 90,94,95 
ceiling function 65 

character 1 

character constants 12 
character mode 5 

character set 217 

circular function 73 

CLEAR 32,35 

CLEAR WS 3 

CMD key (command key) 7 
comment symbol 138 
communications adapter 1 
comparison tolerance 35, 140 
complex name 16 

compress function 90 
conditional branch 159 
conjugate function 60 
console control 14,145 
CONTINUE 32,35 

control information 189, 194 
COPY 32 

copy control dial 212 

copy display 7 

cosine 73 

create a new datafile 179 
creating a direct access file 188 
CTL 178 

CTL prefix 181, 186 

cursor 1 

customer support functions 29 
cylinder number 42 


DAT 20,178 

DAT shared variable 190, 191 
dataformat 181, 184 

deal function 77 

decimal digits 11 

decode (base value) function 91,112 
default device 28 

default file !D 180 

default type 184 

delete 9 

delete statements 169 

device addressing 27 

device/file number 17,180, 182 
direct access 177,181 

direct access operations 188 
direct access to display screen 186 
direct access type 1,17 

diskette 16 

diskette compress 29 

diskette drives 1 

diskette recovery 29 
diskette-to-diskette-copy 29 
diskette-to-tape-copy 29 
DISPLAY 186 

DISPLAY operation 194 

display registers switch 4 

display screen 1 

display screen control with []CC 146 
display screen, read from 194 
display screen, write to 194 
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displaying a user-defined function 168 
divide function 64 

domain error 73 

DROP 17,32,38 

drop function 104 

dual-language machine 3 

dyadic 157 

dyadic format function 124 

dyadic function 59 


EBCDIC (extended binary coded decimal! interchange code) 
EBCDIC character set 225 

EBCDIC code 185 

edit statements 170 

enclosing quotes 12 

encode (representation) function 91,115 
equal to function 84 

ERASE 32,38 

error messages 235 

ERRORSET 16 

establish a shared variable 177 

exchange data file 41 

exchange data format 184 

exchange with other products 185 
exclusive OR function 88 

execute function 89,123 

existing data file type 185 

expand function 90,99 

exponential function 70 

expunge function [JEX 153,179 


factorial function 75 

file 16 

file header 31 

file ID 17 

file ID, default 180 

filetype 15 

filetype O02 181 

filetype 08 181 

filetype O9 or B9 185 

filetype 10 184 

FILEID 32,39 

fix function []FX 151 

floor function 67 

FNS 33,39 

format function 89, 124 

formatted diskette 31 

formatted tape 31 

format 
APL internal 181, 184, 185 
general exchange 181, 184 
unblocked and unspanned 185 

forms requirements 208 

forward space key 8 

FREE 32,40 

function definition 17, 155 

function editing 168 

function header 156 


general exchange data file 41 

general exchange data format 181, 184 
generalized loader 29 

generalized transpose function 90,110 
global names 160 

global objects 37 

grade down function 89, 101 

grade up function 89, 100 

greater than function 83 

greater than or equal to function 86 


HEX value 42 
HOLD key 5 
hold state 9 


hyperbolic cosine 73 
hyperbolic sine 73 
hyperbolic tangent 73 


/Oerror 18 

1/O processor 177 

ID= (file ID) 180, 183 

IMF (internal machine fix) 14, 36 
IN operation 179, 187 

in process 10 

index generator function 89, 104 
index of function 90, 105 

index origin 35,141 

indicator lights 1 

initialization function 25 

inner product operator 129 
input 1,177 

input/output operations 177, 187 
input/output summary 204 

INR operation 182, 193 

insert 8 

insert forms 209 

insert statements 169 

integer 11 

interactive functions 164 

internal checks 3 

internal storage 31 

invalid disk file name 16 

invalid parameter 16 

[OR operation 182, 188 

IORH operation 182,188 


key value 192 
keyboard 1 


keyboard input selection with []CC 147 


label display 29 

labels 158 

laminate function 90,96 
laminated records 190 
latent expression []LX 143 
left argument 29 

less than function 85 

less than or equal to function 87 
LIB 23,33, 41 

line counter []LC 143 
LINK 18, 33, 43 

LOAD 32, 44 

local names 160 

locked functions 167 
logarithm function 72 
logical (boolean) data 12 
L32 64 R32 switch 3 


magnitude function 68 
MARK 23,32, 45 
mathematical gamma function 75 
matrix 15 

matrix divide function 91,121 
matrix inverse 89,121 
maximum function 66 
maxsize 46 

membership function 91, 120 
message INTERRUPT 6 
microcoded programs 43 
minimum function 67 

minus function 62 

monadic 157 

monadic format function 124 
monadic functions 59 
MSG=OFF 180 


N-rank arrays 59 

name classification function []NC 154 
name list function[|NL 153 

NAND function 81 

naperian base 70 


‘national graphics 225 


natural log function 71 

negation function 61 

niladic 157 

NOR function 82 

not equal to function 88 

not function 80 

number of records to access 189 
numeric key 4 

numeric value precision 12 
numeric value range 11 


Index 
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object 34 reshape function 90,93 


operation to be performed 179 residue function 69 

OR function 79 restart procedure 2 

OUT operation 179, 187 restart switch 3 

outer product operator 132 RESUME 32,51 

OUTF operation 182, 188 retract the shared variable offer 198, 199 
output 2,177 return code 179 

OUTSEL 33,47 return codes 200 

OUTSEL OFF 196 reverse display switch 4 

overlapped printing 15 reverse function 89, 105 

overstruck characters 12 REWIND 23, 33, 52 


right argument 29 

roll function 77 

rotate function 90, 107 
rotation function 90 


pair of shared variables 178, 181 
parentheses 138 

password 34 

PCOPY 32,48 


pi times function 72 SAVE 32,52 
power function 71 scaled representation 11 
power on/off switch 3 scan operator 134 
primitive mixed function 89 scientific notation 11 
primitive scalar functions 59 scroll up key 5 
print data 186 search by key 192 
print width []PW 142 search complete 192 
printer 15, 207 sector 21 
printer stacker 215 sector boundaries 21 
printing data 196 sequential access 17,177,179 
printing precision []PP 142 sequential access operations 187 
PROC 17,33, 49 serial |/O adapter 1 
procedure file 17 set tab with []CC 149 
PROTECT 32,50 shape function 89,92 
PRT 186 shared variable 9,177 
PRT operation 196 shared variable offer 177 
pseudoinverse of the matrix 121 shared variable pair 178, 181 
SI 33,53 
signum function 62 
sine 73 
SINL 33,53 
SORT 33,54 
quad 137 special character combination 4 
quad quote 137 specifying the operation 179 


stacker 215 

standard APL character mode 4 
starting character number 194 
starting record number 189 


stop 175 
random link [JRL 143 strong interrupt 6 
random number seed 35 successful operation 200 
ravel function 89,94 surrogate name 178 
read a direct access file .188 SYMBOLS 32,54 
read data from a data file 179, 187 syntax 35 
read file header 185 SYSAREA 16 
read fromafile 182 system functions 145 
read multiple records 184, 190 system variables 139 


reading a direct access file 193 
reading from the display screen 194 
reading records 190 

reciprocal function 64 

records, laminated 184 

reduction operator 127 

reopening function definition 171 
replace aribbon 212 

replace statements 169 
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take function 90, 103 

tape data cartridge 23 

tape recovery 29 
tape-to-tape copy 29 
terminating the operation 197 
times function 63 

trace 173 

trace and stop controls 16 
translated data 185 
transpose function 89,109 
trigonometric function 74 
TV monitor 249 

type of file 181, 184 
TYPE= 181, 184 

TYPE=A 181, 184 
TYPE=I 181, 184 


TYPE=M 185 
TYPE=N_ 185 
TYPE=U 185 


unblocked and unspanned format 185 
update a data file 182 

update a direct access file 188, 191 
user-defined functions 6, 155 


variable and file names 16 
VARS 33,55 
VOLID 32,56 


weak interrupt 6 

workspace available []WA 143 
workspace [ID 34 

write data to a data file 187 
write multiple records 191 
write to a direct access file 188 
write toa new file 182 
write-protect indicator 42 
writing records 191 

writing to the display screen 194 
WSID 32,56 


5103 Printer 207 
5110 compatibility 227, 229 
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